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VIEWPOINT 


By Avi Rappoport 


X Here Now 

For some odd reason, the keynote at WWDC 
(Apple World Wide Developer Conference) was 
supposed to be a “fireside chat”* There was amused 
speculation in the crowd about what that would mean, 
but it turned into a normal Steve Jobs and Avie 
Tevanian keynote with a graphic of a fireplace. It was 
a housewarming party for Mac OS X, partly designed to 
convince developers to work on native applications 
but also very much directed at the press. I would have 
liked to see less flash and more real information about 
Apple's commitment to fixing OS problems and 
improving development tools. 

The RDF 

Those of you who haven't been to a Steve Jobs talk 
may not believe in the RDF (Reality Distortion Field), 
but it's a real thing. Think of the best and smartest 
salesperson you know, selling something they helped 
build and really love. Jobs is sincere and that makes 
him hard to resist. I remember walking out of the first 
presentation of the NeXT machine at BMUG in 1988 
going “wow that's cool”. And so is Mac OS X, though 
it T s more of an adolescent NeXTStep than anything 
else, 1 was pleased to hear Jobs say that they know X 
10.0 is not perfect, that they think of it as a 
“tremendous start”, and that they retained the feedback 
database with over 40,000 items in it. Both end users 
and developers are demanding better performance and 
1 hope by the time you read this, you 11 be seeing major 
speedups, So the RDF may be a good thing here! 

Jobs talked about the power of Unix and the 
simplicity, elegance and applications of the Mac, and 
pointed out that Apple will soon become the largest 
Unix supplier in the world, which got a big hand from 
the audience. The crowd also liked Jobs’s manifesto 
about why the company is opening stores, and a 
charming video of the first day a store was open, full 
of cheerful customers and happy sales people, I was 
happy to see the realistic approach of installing both X 
and 9 on shipping machines, but defaulting to 9 — I 
was worried about my mom and other fragile Mac 
users being stuck with the unfinished X. 


Mac OS X 

The main message was that all developers should 
write X-native applications right away. Jobs and Avie 
Tevanian both made a big deal about a Macworld 
Magazine survey of PowerBook owners and their plans 
to upgrade to X and to native X applications. This 
culminated in a thinly-veiled threat that customers 
would migrate quickly from Classic applications to 
native X applications, perhaps by the end of summer. 
Maybe they were spooked by developer reluctance, but 
a lot of folks don’t respond well to such negativity. 

Apple would only talk about X version 10.0.x, not 
future changes, which was a big change from previous 
conferences! There were some nice demos, including a 
MIDI keyboard program that continued to work without 
a hitch even when Tevanian was opening other 
applications such as email. And everyone loved watching 
the PowerBook wake up instantly, and the company 
commitment to standards (such as OpenGL) rather than 
proprietary code. However, the listing of all the features 
of Mac OS X were not too exciting, I noticed that there 
was a lot of restlessness in the audience. 

The demo of developing a native Cocoa program 
using Interface Builder was supposed to show how 
easy it is to wire together an application. Cynics in the 
audience noticed that the example QuickTime editor 
requires 1,000 lines of code that we never saw: it was 
something of an insult to programmers to show them 
smoke and mirrors like that. PowerPlant and C++ can 
do the same, though the demo is less whlzzy. Again, 
the general press might be wowed, but not many folks 
who have tried to write code. 

Some of my developer friends really like Interface 
Builder and Objective C, buL most are not interested in 
learning a new language on a minority platform, even if it’s 
Mac OS X, They’ll stick with C++ or Java, but are concerned 
about speed issues. They want to see more effort put into 
performance and making all the features of Carbon work 
properly, especially the low-level drivers. Jobs and Tevanian 
were intent on convincing people to write native Mac OS X 
applications, but are they providing enough OS support? The 
keynote was too overbearing, though the rest of the 
conference was more positive: time will tell if Apple responds 
to what developers really need. HQ 


Avi Rappoport doesn't write much code any more, now she's an analyst and consultant specializing in web site and intranet search engines at 
www.searchtQ0ls.com. Yes, her name is pronounced like Avie Tevanian. but she was here first and is older anyway. 
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GETTING 

STARTED 


By Erick J. Tejkowski 


REALbasic 3 -The Marriage of Old and New 


Old World Mac Development meets New 
World Features 

Introduction 

Coincidental with the release of Mac OS X, REALSoftware 
announced the latest edition of their popular programming 
environment — REALbasic 3* REALbasic, a visually based, object- 
oriented BASIC environment for Macintosh, has always amazed 
fans in the past, The latest version is poised to do the same. With 
the introduction of a new operating system like Mac OS X comes 
the need for applications — and lots of them. REALbasic gives 
you the chance to create such applications, while simultaneously 
affording you the opportunity to reach out to other platforms 
with minimal effort. This fact alone may reason enough to 
warrant looking into REALbasic, but REALSoftware has also 
loaded REALbasic with all kinds of other powers. 

Something Oid 

REALbasic 3 continues along the path of earlier versions by 
providing an easy-to-use cross-platform visual programming 
environment for the Mac OS, The latest incarnation of REALbasic 
builds on previous versions (REALbasic 1 & 2), so you will be 
glad to know that your old code should transfer to REALbasic 3 
without a hitch. All of the familiar commands, controls, and 
features are there for your instant programming gratification. 

There are, however, a few changes you should note. For 
starters, adding a resource file to your project works just as it always 
has, but now it is quite a bit friendlier, Previously, you were 
required to give an external resource file the name Resources for it 
to be recognized in the REALbasic IDE. Now, you are not limited to 
one external resource file. Instead, you may simply add a .rsrc 
extension to any file and it's fair game for inclusion in your project. 
Therefore, it is now possible to have multiple resource files in your 
REALbasic project, In the event that you mistakenly include multiple 
files with conflicting resources (i.e. the same type and number), 
REALbasic simply overwrites earlier resources based on the order in 
which they appear in the Project Window. 


Another important function that carries over into the latest 
version of REALbasic is the Declare statement, The Declare 
statement permits you to access Macintosh and Windows 
Toolbox calls directly from you REALbasic code, something that 
once was only possible with a plugin. REALbasic 3 continues to 
give you this ability and ups the ante by additionally providing 
access to Carbon calls. This requires a few code changes on your 
part, but luckily, the transition is nearly painless. Whereas the 
Classic Mac OS toolbox calls relied upon an assortment of 
libraries, Carbon code typically relies strictly on one library: 
CarbonLib. Updating your toolbox calls for Mac OS X often 
merely entails a library name change. If die syntax of the Carbon 
call lias changed from its Classic predecessor though, you will 
have to change it as well. (See Listing 1). 

Here is what a sample routine might look like: 

Listing X: Declare statements in Classic Mac OS versus Carbon 

The only difference between most Class Mac OS Toolbox calls 
and their Carbon counterparts is a simple library name change. 

Declare Function SetSysBeepVolume Lib "InterfaceLib” 

[Level as Integer) as Integer 

Declare Function SetSysBeepVoiume Lib “CarbonLib'* 

(Level as Integer) as Integer 

Something New 

In addition to updating existing features, REALbasic adds a 
host of new abilities. Some of these features ease the transition 
to Carbon, while others are there just to simplify your life and 
make the REALbasic experience more pleasant. 

The IDE 

REALSoftware has made some nice changes in the 
REALbasic IDE. For example, you may now save your REALbasic 
projects in one of three formats (see Listing 2). 

Listing 2: REALbasic 3 File Formats 


Erick Tejkowski is the author of REALbasic for Dummies published by Hungry Minds. You can reach him at etefkowski@mac.com. 
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database development projects. 
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Save As enables you to save your REALbasic projects in one of 
a number of formats rather than only one like in earlier versions. 

Standard Project — REALbasic 3 format 

REALbasic 2.1 Project - Provides backward compatibility. 

Without this feature* you would have to rebuild your projects 
if you ever wished to migrate back to REALbasic 2.1. 

XML - A new format for REALbasic* The Project saves as an XML 
text file to encourage REALbasic tool development. 


Furthermore, REALbasic 3 adds a bit of automation by 
making the build process Apple-scriptable. This allows you to 
perform builds under the power of an AppleScript. Figure 1 
shows the REALbasic AppleScript Dictionary. 



Figure L The REALbasic 3 AppleScript Dictionary. 


Continuing on the path to making your life easier, 
REALbasic 3 makes dramatic improvements to the Auto¬ 
completion feature. As you type, REALbasic presents you 
with a list of possible commands, objects, methods, and 
property names; usually by the time you have typed the 
second or third letter of the word (see Figure 2), As you 
type, you see ellipses appearing directly after the cursor. 
When this occurs, press Tab and a list instantly appears 
displaying REALhasic’s guess as to what you wish to type 
next. Select the one you want and hit Return. This is a gem 
for all those hunt-and-peck programmers out there. 



Figure 2 The REALbasic 3 Auto-Completion Feature 


The REALbasic IDE also has some subtle navigation 
enhancements w^orth mentioning. The Code Editor has been 
updated with a few r interface widgets that help you get 
around the environment quicker. Located at the bottom left 
corner of the Code Editor (see Figure 3), four small buttons 
give you instant access to navigation functions. The first 
button opens the Window Editor belonging to the current 
Code Editor in which you are entering code. The second 
button lets you toggle between showing all events and only 
the event you are working with. The third button takes you 
back in time to the last place your cursor rested in the Code 
Editor, Like multiple undos (which REALbasic has), your 
cursor can continue traversing backwards in time. The fourth 
button, as you may have guessed, lets you go in the opposite 
(forward) direction. 



Figure 3* The REALbasic Code Editor provides 
some navigation options. 
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Carbon 

REALSoftware released the third version of REAIbasic alongside 
another major product release — Mac OS X. This was no accident 
Perhaps the biggest news about REAIbasic 3 is the tact that it can 
now compile Carbon versions of your projects, often with little or no 
change to your existing code. Your applications gain protected 
memory, Core Graphics text drawing, and other Carbon 
technologies with no additional effort on your part. Figure 4 
displays die new Build Dialog where creating Mac OS X compatible 
software is as simple as clicking on a checkbox. 



Figure 4 The Build Dialog shows how easy it is to create 
Carbon applications — one checkbox / 


Although most code works “as-is" in Carbon builds, there 
may come a time when you need to address some specific facet 
of Mac OS X development. For example, Declare statements 
often differ based on the intended target platform. (Classic Mac 
vs. Mac OS X vs, Microsoft Windows). To facilitate platform 
specific code with Mac OS X, REAIbasic 3 adds the 
TargetCarbon directive. Listing 3 shows it in action. 

Listing 3* Targeting Mac OS X code 


The TargetCarbon preprocessor directive permits von to 
address Mac OS X — specific code, 

it if TargetCarbon 

Declare Function SetSyeBeepVolume Lib “CarbonLib" 

[Level as Integer) as Integer 

Jfelseif 

Declare Function SetSysBeepVolume Lib “InterfaceLTb M 
[Level as Integer) as Integer 

/fend if 

The Shell Class is another great new feature available in 
REAIbasic 3 for the first time. With it, you can perform 
command line functions within your own projects. This 
creates all kinds of possibilities for enterprising individuals to 
create GUI-based applications for those command-line shy 
Mac users out there (and believe me, they exist). For 
Microsoft Fans, this feature also works on Windows (DOS 
anyone?). Figure 5 shows the Shell Class in action and the 
pictured example is available on MacTech s ftp site. 
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liiis feature is a welcome addition. 
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Figure 5, The REALbasic Shell Object in action. 

Executing a shell script is as easy as creating a new Shell 
Object and sending it the Execute command. Listing 4 shows 
how to list the current processes in an EditField. 

Listing 4: Executing Shell Scripts 

REALbasic 3 affords you the chance to execute shell scripts 
just as you do from the command line. This example lists the 
current processes and the corresponding PID number. 

Dim myShell as Shell 
toy She 11 - Hew Shell 

tnyShell.Execute “ps x | awk 1 (print $11 (print $51* “ 
if my Shell. Err or Code = 0 then 
EditFieldl.Text - rayShell.Result 
end if 


iDisk 

REALSoftware has always been a very open company when it 
comes to pre-release software. They hive always believed that user 
should be able to take advantage of bug fixes and feature additions 
as they progress. As such, it is wise to chase down the most recent 
version of REALbasic, as it is typically quite .stable and often provides 
useful new functions. Prior to REALbasic 3-lb7* EEALbasic was only 
available online directly from REALSoftware. Now, Apple Ls offering 
the latest download of REALbasic on iDisk. With iDisk you do not 
even need a web browser to gain instant access the latest version of 
REALbasic. Just mount iDisk on tire desktop and find REALbasic in 
the Software directory. Now, that’s cool] 

Something Borrowed 

Existing REALbasic developers will be glad to know that it 
continues to support a vast collection of technologies, even 
within Carbon applications. QuickTime and AppleScript support 
are there like before, but don’t forget that REALbasic can take 
advantage of the many new features inherent to both of these 
technologies. Its like getting bonus features free! 

Furthermore, REALbasic 3 supports MIDI, MP3, and MPEG files 
using Windows Media libraries now. Previously, you were required 
to use QuickTime. Despite QuickTime’s popularity, more Window’s 
users take advantage of the Windows Media Player technologies, so 


Something Blue 

Everything is turning blue! No, you do not need a new pair 
of glasses, it is just the Aqua interface you are seeing. Along with 
Carbon compatibility, REALbasic makes the switch to Aqua 
painless. REALbasic 3 uses the Aqua interface under Mac OS X. It 
also permits you to build applications using the Aqua interface. 
This all happens transparently to the user. Build projects like you 
always liave; they instantly acquire the Aqua interface when using 
Mac OS X. REALSoftware has made the transition to Aqua 
beautifully, although, on occasion, you may need to resize a 
button or two to deal w ith the different sized fonts cm Mac OS X, 
Figure 6 shows REALbasic in all its Aqua glory. 



Figure 6. REALbasic 3 b Aqua all over. 


Affer the Honeymoon 

REALbasic, like Mac OS X, is in a bit of a transitory state at the 
time tiiis article was written. At this point, everyone is expecting an 
update to Mac OS X in the near future. REALSoftware is following a 
similar path by readying REALbasic 3-E The Beta versions of 
REALbasic 3-1 are publicly available (see the URL list at the end of 
tliis article). Because Carbon Ls in a state of flux, REALSoftware 
recommends checking the Beta version of REALbasic should the 
REALbasic 3.0 version lack some feature you require. Keep in mind 
that Apple released the final Carbon libraries only shortly before tile 
release of Mac OS X. Once it did, REALSoftware began revising 
REALbasic to reflect the changes therein. Thus, the Beta version of 
RFALbasic 31 provides a glimpse into the latest work coming out of 
KEALSoftware s Austin offices. 

Avoiding Divorce 

Some programmers may Ine wondering what value there is in 
purchasing a programming environment like REALbasic when Apple 
gives away free tools with Mac OS X. litis is a valid question, but not 
necessarily a good assessment of the situation. Although Project 
Builder is essentially free for Mac OS X users, it relies on the more 
complex Objective C and Java languages for all coding. It does not 
permit BASIC source code, an undeniably easy language to leam. 
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Moreover, REALbasic provides the only cross-platform visual 
development environment on the Macintosh. Project Builder doesn't 
do Windows! Finally, REALbasic also provides some features 
unavailable to Project Builder users. For example, REALbasic comes 
stocked with a database engine, a sprite engine, XCMD support, and 
more. Sometimes, you truly get what you pay for. 

Conclusions 

In this article, we took a brief look at the new and updated 
features of REALbasic 3- Although much of it appears similar to 
past versions, it is clear that much work has gone into its 
development. Not only does it make improvements to existing 
technologies, but it also manages to make it easier than ever to 
produce quality Macintosh and Windows software. Creating 
software for Mac OS X has never been easier either. EEALSoftware 
made the transition as painless as Apple made the 68K to PPC 
change nearly a decade ago. All of your old code works just as it 
always did, but now on Mac OS X, 
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Basic Windows 


How one goes about writing a 
PowerPlant application 

These Articles 

This is the third article in a series of articles about 
Metro work s’ PowerPlant application framework. The First 
article introduced how the framework deals with 
commands and the second article discussed the 
debugging facilities of the framework, This article focuses 
on the window classes in the framework. This series 
assumes familiarity with the C++ language, the Macintosh 
Toolbox API and the CodeWarrior IDE, The articles were 
written using CodeWarrior 6 with the net-update to IDE 
4.1.03 and no other modifications. Throughout this and 
future articles, I will assume that you are using the class 
browser and the debugger to explore the PowerPlant 
code more fully. 

Panes, Views and Windows (oh my) 

Windows provide your users the ability to view their 
data and so they will be a fundamental part of your user 
interface. PowerPlant helps you in providing this visual 
interface through its LPane, LView and LWindow classes. An 
LPane is something that is drawn on the screen. An LView 
is an LPane that may contain other LPanes (which allows 
you to design a visual hierarchy), An LWindow is usually 
the topmost LView in a visual hierarchy and it is derived 
from both LView and LComrnander. The PowerPlant Book 
spends multiple chapters on these classes so you can 
(correctly) assume that I will leave a lot unsaid. The 
purpose of this article is to introduce you to Constructor 
and some of the basic code needed to work with the visual 
hierarchy in PowerPlant. 

Constructing Windows 

My general pattern of development is to first set up 
the visual hierarchy in Constructor and then write the 


code to support that hierarchy. This ordering is not 
required and I frequently go back and forth between 
Constructor and the CodeWarrior IDE. For the sake of 
keeping the article short, we will inspect the 
AppResources.ppob file first and the source code second. 
The application uses three windows; a document window 
for text editing, a dialog that requests information from 
the user and a floating window for displaying information 
to the user. We will examine the document window first, 
Double-clicking the AppResources.ppob in the project 
window should launch Constructor. You can do this resource 
editing in Resourcerer (using templates provided) or in 
ResEdit (if you are really gut at hex), but I have always found 
Constructor more convenient. The discussion here is limited 
(remember, this is an introduction to PowerPlant, not a 
reference) but you can find more information in the 
Constructor User Guide on die CodeWarrior CD. Double¬ 
click Lhe “Document Window” resource (you may need to 
expand the Windows & Views group to see it) and select 
Show Object Hierarchy from the Layout menu. A document 
window has three nested views: an LWindow object 
containing an LScrolierView object containing an 
LTextEditView object (well, not quite, but we will get to that 
in a moment). Open a Property Inspector window (from the 
Windows menu) and select the LWindow from the Hierarchy 
window. Most of the properties should be familiar to you if 
you have worked with Macintosh window. You can learn 
about many of the ones that aren’t familiar by adjusting them 
and then running the application. The first property is the 
Class ID that is used by PowerPlant to determine exactly 
what sits In each resource, we will explain it later, but for 
now you will want to leave it untouched. 

inside the LWindow is an LScrolierView that handles the 
scrollbars for the window. Click on it in the Hierarchy 
window and look at its properties. LScrolierView is derived 
from LPane and the first set of values is used by the LPane 
base class. The Pane ID is necessary if you need to have 
access to this pane from your source code, since I don’t 


Aaron teaches in the Mathematics Department at Genual Washington University in Ellensburg, WA. Outside of his job, lie spends time riding his 
mountain bike, watching movies and entertaining his wife and two sons, You can email him at montgoaa@cwu.edu, try to catch his attention in the 
newsgroup comp.sys mac.oop.powerplant or visit his web site at mac69108.math,cwu.edu:8G8Q/. 
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access the scrollbars from the source code Fll leave ir set 
to 0, Just like the LWindow resource, don’t change the Class 
ID number. The LScrollerView is 2 pixels higher and wider 
than the enclosing window (and placed one so that it 
extends 1 pixel beyond each edge). 1 can never remember 
the appropriate values for the Height and Width properties 
so I usually dig around in the PowerPlant stationary or 
PowerPlant examples and examine the values there. This 
LScrollerView is bound to all four sides (so it will expand 
in all directions if the window expands). The second set 
of properties is specific to the LScrollerView class. The first 
is the thickness of the scrollbars as welt as their 
positioning. Again, 1 don't typically remember these off 
the top of my head and so 1 end up looking in stationary 
and example files. By setting the horizontal scrollbar's Left 
and Right properties to -1 we cause it to be absent. The 
vertical bar is set to 0 from the top and 15 from the bottom 
(more values gleamed from other sample resources). The 
Scrolling View ID is the Pane ID of the pane that the 
scrollbars will control (in this case, it is the LTextEditView). 
I have activated Live Scrolling. 

Inside the LScrollerView is something based on an 
LTextEditView. If you look at an untouched LTextEditView, 
the Class ID is txtv, but this has a Class ID of Htxv. We are 
not going to be using a LTextEditView in our application, but 
rather a subclass called CHTMLTextView, Since the subclass 
doesn’t need any more data than what is in a LTextEditView 
resource, the easiest way to create a resource for a 
CHTMLTextView is to use the LTextEditView template and 
then change the Class ID. The effects of this change will be 
discussed below when we talk about the source code. I’ve 
discussed the LPane properties in the last paragraph. Since 
I will try to access this pane from the source code, I 
needed to give it an “honest” Pane ID and 1 choose Text 
since this is the text view. The choice to give the 
LTextEditView a 2 pixel edge is again based on looking at 
various samples. The LView properties are left untouched 
(and are explained in The PowerPlant Book). 

The LTextEditView properties contain TextEdit Hags that 
affect the Macintosh TextEdit structure. I have set Word 
Wrap on (since I have eliminated the horizontal scrollbar, 
this is important). The TextTraits is a resource [D and 
checking the appropriate resource in Constructor shows 
that these traits set the font size to 12 and the font to 
Monaco (since it is mono-spaced). The TEXT resource ID 
is the location of the original text in the window (the TEXT 
resource is in the file App Resource, rsrc since I use 
Resourcerer to edit it). In some later article, I might talk 
about how to create templates so that you can add data to 
be edited in Constructor for your classes. 

Before looking at the other two windows, a natural 
question might arise: where did these I get these classes to 
put into the hierarchy? You can create a new window 
resource by dragging an item from the Windows tab of the 
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Catalog window (choose Catalog from the Window 
menu) into your resource file's window. Then you open 
the window you just created and build the hierarchy 
within tills resource by dragging items from the Catalog 
Window into the resource's window. You should probably 
spend some time just browsing your options. One thing to 
notice is that some visual features appear more than once. 
In Lhe Views tab, you will find an LScroller, an 
LActiveScroller and an LScrollerVlew. The first two pre-date 
appearance classes but I cannot seem to find any 
PowerPlant documentation that helps you make this 
determination. If you add these to your window and then 
try to register them in your source code (a step described 
below), you will be required to add files to your project* 
This is an indication that a newer class is available. Other 
examples are the LRadioGroup in the Other tab (replaced 
by the LRadioGroupView in the Views tab) and LEditField in 
the Panes tab (replaced by LEditText in the Appearance 
tab). The easiest way to determine what to use is to dig 
around in die sample ppoh files provided by Metrowerks, 
The next window, Glossary Window, is a floating 
window. The actual steps in constructing it are not very 
different from the steps required in the previous example. 
The only things I will point out are that the LTextEditView 
is set to he neither Selectable nor Editable. 


5 P 0 TLIQHT 

seven times faster 


free demo 
www.onyx-tech.com 


Find memory errors mifomuticalfy irr source 
Code Fragment Support 
Leaf Detection 

^jpF Toolbox Pfuameiei Chi ■ fmi 



The final window is a dialog box. This is created by 
dragging an LGADiaiog from the Catalog window to your 
resource file’s window'* You can then create the visual 
hierarchy in the same manner as for regular windows. You 
will need to set the Default Button ID and the Cancel 
Button ID. This will allow your dialog to correctly handle 
user requests from the keyboard. When you actually create 
those buttons, you will set their messages to msg_OK and 
msg_Cancel and check "Is Default Button" for the OK 
button as well. We will discuss the messaging mechanism 
in PowerPlant in more depth in the fifth article, if you 
cannot wait, look in The PowerPlant Book. 

The only other changes are the removal of the Bad 
Things menu, the addition of two commands to the Edit 
menu and the addition of an Insert and a Glossary menu. 
You should be able to determine how these were created 
and what they do from the first and second articles so I will 
move on to discussing the changes to the source code. 

Checking that the class hierarchy has been 
constructed correctly can be done using the Visual 
Hierarchy menu item in the Debug menu* This will 
present a floating window displaying all of the hierarchies 
of the front-most regular application windows. You can 
even identify panes by moving the mouse over them and 
watching the pane information turn green in the Visual 
Hierarchy window. 

Changes To Earlier Classes 

Just as PowerPlanl has two implementation files for 
the UDebugging*h header, there are three implementation 
files for the U Desktop, h header. The basic implementation 
is UDesktop.cp* UFIoatingDesktop.cp should be used if you 
use floating windows. Finally, UWMgr20Desktop*cp should 
be used if you know that the code will be run using 
version 2.0 of the Window Manager, This project uses 
UFIoatingDesktop.cp because it does contain floating 
windows, but does not require any of the 
UWMgr20Desktop.cp implementations. 

There are no code changes in the main() function so 
we turn our attention to the C DocumentApp class. We 
remove all the Bad Things code from the previous article 
and add the Lookup command (which is always enabled). 

This moves us to Lhe CTextDocu merit class. Although 
very little of the code is new, we will explain some of the 
existing lines of code for the first time. We start with this 
classes constructor: 


CText Doc u me n t * ep 

CTextDoeument:: CTextOocument ( 

LCommander* inSuper) 

: LSingleDoc(inSuper) 

I 

mWindow = LWindow;:CreateWindow(FFahJTextWindow, this ); 
ValidateObject_(mWindow): 

my Text Vi gw = 

FindPaneByID_(mWindow T kTextView, CHTMLTextViev): 
Validate0bject_(myTextV1.ewi *, 
mWindov->SetLatentSub(myTextView): 
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NaneNewDoc () ; 
mWindow->Show() I 

} 

The LSingleDoc class (CTextDocumerit’s superclass) has an 
LWEndow* member data named mWindow. We use this store a 
pointer to the document’s window. The call to CreateWindow() 
takes a resource id as well as a commander In the first article, 
you learned that the commander will be the window’s 
supercommander. Here we discuss how PowerPlant builds the 
LWindow from the resource. The actual conversion from resource 
data to class object is done by the PowerPlant classes called 
UReanimator and URegistrar, PowerPlant opens the resource as 
an LStream, Then PowerPlant reads the first four characters of 
the resource and looks these up in a static table that associates 
four-character codes to class constructors taking an LStream as 
input, If’ the four-character code is found, then die associated 
constructor is used to create the object. If die four-character code 
is not found, an exception is thrown. You can witness such an 
event if you replace the Class ID of die CHTMLTextView object in 
the Document Window with HTXT and then run the application. 
The natural question now is how PowerPlant knows which 
constructors are associated with which Class IDs, The static table 
used is generated by calls to the macro Regi$terClass_(), 'Ilils will 
associate die class’s class JD four-character code with the class’s 
stream constructor. You will need to make sure all of your 
PowerPlant resources are properly registered before you attempt 
to read them in from the file. You can use the Validate PPob... 
and Validate All PPobS menu items from the Debug menu to 
verify that you have made all of die necessary registrations. 

Once we have a pointer to the window, a natural thing to 
do will be to try to access die things in the window. In this 
particular instance, we will want to establish the text view as the 
latent sulxommander for the window (meaning dial when the 
window is placed on-duty, die text view takes control). You can 
access the subpanes of a window using the FfndPaneByJD_() 
macro. This macro takes the window, the Pane ID and the type 
of dial pane as its input. If you access a pane w ith this macro, 
you will need to make sure that the pane has a unique Pane IT). 
The FindPaneBylD_() will attempt to find the subpane using the 
given information and cast it to the appropriate type (throwing 
an exception if either of these operations fail). Now that we 
have a pointer to the appropriate commander we can establish 
it as die latent subcommander 

CHTMLTextView 

The CHTMLTextView class derives from the 
LTextEditView class and adds some features appropriate for 
editing HTML code. We examine some of the class 
declaration first. 


CHTMLTextVIew.fi 

class CHTMLTextView 

: public PowerPlant: .'LTextEditView 

I 

public: 

eniim f class_ID = FOUR_CHAR_CODE (* Ktxv') ]; 


CHTMLTextView(); 

CHTMLTextView(PowerPlant::LStream‘ 

inStream )i 

//remainder omitted 

I ; 

The first tiling to notice is that the class defines classJD to 
be Htxt so that the RegisterClassJ) macro will work correctly. 
You should choose classJDs that contain some uppercase letters 
(because PowerPlant reserves those which are all lowercase). 

Before presenting die code, Ill explain what CHTMLTextView 
does that a regular LTextEditView does not do. A CHTMLTextView 
knows how to insert a few of the HTML tags into the document, 
when it does this insertion, it places a marker (the character •) in 
places which should be filled out by die user. The user can dien 
use the Goto Next Marker and Goto Previous Marker items in 
die Edit menu to jump from dieir current location to die next for 
previous) marker. (If you use Alpha as a text editor, dien diis 
behavior probably looks familiar). The CHTMLTextView is also 
capable of insetting appropriate HTML tag templates (using the 
marker for items to lie supplied by die user). Some of the code 
allowing CHTMLTextView to handle these requests is below, 

InsertTagO CHTMLTextView. cp 

void CHTMLTextView::InsertTag(const std::string& inOpen. 
const std::string^ inClose) 

( 

TEHandle theTextEditH = GetMacTEH(); 

StHendleLocker 

theLock(reinterpret_cart<char* *>(theTextEditH)); 

short theStart - (* 'theTextEditH).selStart; 
short theEnd = (*"theTextEditH),selEnd; 

if UheStart = theEnd) 
i 

string theMarker = *”;: 
theMarker += Marker£}; 

Insert(theMarker.c_str(), theMarker,lengttrQ ); 
theEnd " theStart + 1; 

I 

SetSelectionRange(theEnd, theEnd): 
insert(inClose.c_str(). inClose,length()) ; 

SetSelectionRange(theStart ( theStart); 

Insert(inOpen.c_str(). inQpen.length ())\ 

SetSelectionRange(theStart» theStart); 

I 

We obtain the TEHandle directly with a call to 
GetMacTEHQ and then use a StHandleLocker to lock the 
handle until the StH and leLocker * 1 s destructor is called. 
Although it is unlikely that the lock is currently needed 
and so the lock is unnecessary, that might make the code 
fragile if the PowerPlant code changed. Furthermore, 
because the lock is controlled by an object on the stack, 
1 feel confident that the lock w ill be released. We obtain 
the starting and ending of the selection directly from the 
TE Handle. If no item is selected, we insert a marker into 
the text and make it the current selection. Then we insert 
the tag close and tag open and place the cursor at the 
start of the tag. The code needed to go to the next marker 
has a similar flavor 
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GotoNextMafkerO in CHTMLT'cxtView.cp 

void CHTMLTextView::GotoNextMarker() 

1 

TEHandle theTextEditH = GetMacTEHO; 

StHandleLocker 

theLockl(rernterpret_east<char* * * >(theTextEditH)}i 

short theEnd = (** theTextEditH) *selEnd; 
short theLength = (*'theTextEditH],teLength; 

Handle th eTextH = ("theTextEditH)* hText; 

StHandleLocker theLock2(theTextH); 

for (short thePosition - theEnd; 
thePosition 1= theEnd - 1: 

-H-thePosition) 

t 

if [thePosition > theLength) 

1 

thePosition = D; 

I 

if ( * (('theTextH) + thePosition 1 = Marker 0 ) 

I 

SetSelectionKange[thePosition, thePosition + 1}; 
return: 

1 

) 

I 

Both of these panes use PowerPoint's code to handle 
drawing and user inter-action. If you need to override 
these (and other) routines, you need to be aware of how 
PowerPlant factors the work. There is both a Draw() and a 
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DrawSelfQ method, similarly, there is both a C!ick{) and a 
ClickSelfQ method. You should override the DrawSeifO 
method and call Draw{) method in your source. The Draw() 
method will do the necessary set up, then call the 
DrawSelf() method and then do the necessary tear down. 

CGlossary 

The CGlossary class provides a first glimpse into how 
dialogs are handled in PowerPlant (they wall be discussed 
more in depth in the fifth article). The first thing to notice 
is that C Glossary's constructor is private and 
unimplemented. This is because the class currently has no 
data and only static methods. The class could have been 
implemented as a namespace at this point, but it has been 
written as a class to allow for the possibility of future 
improvements (for example, storing the glossary data in an 
associative array in RAM). The class only has two methods: 
RegisterClassesQ and Lookup(). RegisterCiasses{) does the 
usual task of registering those visual classes which are used 
by the CGlossary class and is not presented here. The 
Lookup() method is overloaded with two implementations. 
The first takes no arguments, presents the user with a 
dialog asking the tag to look up, and then invokes the 
second version. The second version takes a string argument 
and presents the user with the tag’s glossary information (if 
iL exists). Their code is presented below. 

LookupQ from CGIossary.cp 

void CGlossary::Looku p() 
t 

unsigned char theString [256]: 

theString[0] “ *\Q'; 

StDialogHandler theHandler(k_PPoh_GlosEaryDialog, 

LComuianderi iGettopCamander ()}: 

LWindow* theDialog = theHandler.GetDialog(); 

LEditText* theField 

* FindPaneByID_{theDialog, 

kJaneIDT_Lookup. LEditText): 

theField->SetDescriptor (StriragLiteral ..C 4 **) ]; 

theField->SelectAll[); 

theDialogOSetLatentSub(theField) : 

theDialog->Show()j 

while (true) 

I 

Message! hitMessage = theHandler.DoDialog(); 

if (hitMessage = msg_Cancel) 

[ 

return; 

) 

else if [hitMessage = msg_0K) 

I 

theField-JGetDescriptor(theString): 

b reak: 

I 

) 

Lookup(theString); 

I 
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We use a StDiaiogHandler to manage the dialog that 
obtains user input (more on this in the fifth article). We 
pass in the resource ID of the appropriate dialog and 
obtain the dialog window from the Handler. We use 
FindPaneBylD_() to find the LEditText in that window and 
present the window to the user We then enter a loop 
calling the DoDralogQ method of theHandler repeatedly. 
This will return information about what items were hit in 
the dialog. If the Cancel button was hit, w'e simply leave 
the function. If the OK button was hit, we obtain the 
user’s input using the GetDescriptor() method of the 
LEditText and break from the loop. The handler ignores 
any other action by the user. Once the dialog has been 
dismissed we call the other Lookup () method (because the 
OK button was hit). 


Lookup () in CG lossary. cp 

void CGlossary::Lookup(Str255 InTerm) 

I 

StResource theDefinititjn: 

try 

t 

theDefinition.GetResource(k^ReaTypeJCEXT, inTenn. 
true, true): 

I 

catch (...) 

I 

theDefinition.GetResource[k_ResType_TEXT, 
kJ3tr255_Unknown T true, true): 

) 

LWindow* theWindovP 

= LWindow::Createtfindow[k_PFob_GlannaryVindow. 

LCommander: :GetTopContmander{)): 

LTextEditViev* theDefnP 

- FindFaneBy UU( the Window? * k_PaneIDTJ}eflnition, 
LTextEditViev); 

theDefnF->SetTextHandle(theDefinition); 

LStaticText* theTeraF 

= FindFaneByID_(theWindowP, k_PaneIDT_Term, 

LStaticText): 

LStr255 theString = StringLiterai_(*‘< fr ); 
theString +“ InTerm: 
theString += 5trin&Literal_t M > rt ); 
theTertnP->SetDe script or (theString): 


The second version of LookupQ is responsible for 
actually determining and displaying information about the 
tag. The information is stored as resources of type TEXT 
with the name of the tag used as the name of the 
resource. We obtain the resource using a StResource that 
will dispose of the resource when its destructor is called. 
We first try to obtain a resource with the tag's name and 
if that fails, we use a generic error message stored in a 
resource with the name “Unknown". The first true in the 
GetResourceQ call tells the method to Throw_ if there is an 
error and the second true tells the method to only look in 
the current resource file. 

Once we have the text we create a window, use some 
Find PaneBy !□_{)’$ to obtain pointers to some text fields 
and fill them in. We use the LStr255 class from Power? I ant 
for the second field. This class is described in a Mac Tech 


article written by John C. Daub and provides a lot of the 
functionality normally found in the C++ string class for 
Pascal style strings (of length up to 255). The Stri ng Lite ral_ 
macro converts its input into Pascal style strings. 
Currently it is very simple, but using the macro will make 
it easier to adjust if the PowerPlant API changes to C style 
strings at some future point. 

Concluding Remarks 

Well, that provides a user interface to your 
application. Although it was quick and sketchy, it should 
give you some feel for how PowerPlant handles windows. 
We explore how PowerPlant works with files in the next 
article (which is the other half of PowerPlant^ LDocument 
class). The core portion of this series will be completed 
in the fifth article where we cover how PowerPlant 
handles dialogs. Once the core portion is completed, 1 am 
open for suggestions on where to go next, so if you have 
any ideas, please e-mail me, 

PowerPlant References 

References that are particularly appropriate for tills article 
are the following: 

• “Panes", “Views", “Windows” chapters in The 

PowerPlant Book 

* John C. Daub’s “The Ultra-Groovy LString Class” in 

MacTecb, January 1999. ®E3 
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FROM THE 
FACTORY FLOOR 


By Richard Atwell, ©2001 by Metrowerks, Inc., all rights reserved 


The Road from Rhapsody 


Since the last installment of this column in February, Mac 
OS X 1.0 shipped, finally. Developers have gone so long 
waiting for a new operating system based on a “modern” 
core, the release was almost anticlimactic It’s been a long 
road since NeXT and Apple merged back in December 1996 
and Metrowerks has been following the saga from the 
beginning (See the Factory Floor article in MacTecb Vol 13, 
No. 5 and subsequent articles). 

In the earliest days, developers were only able to get 
their hands on a version of GpenStep for x86. Then 
Rhapsody appeared on Lhc scene and continued with a few 
DR versions. Remember when Classic was called the 
BlueBox? Rhapsody morphed into Mac OS X Server then Mac 
OS X came into being in addition to the server version. After 
several Developer Preview (DP) releases of Mac OS X and 
many Carbon SDK releases, developers now have what they 
need to develop seriously for Mac OS X: a stable initial 
version with a rich new set of APIs. 

At WWDC 2001, Code Warrior for Mac OS, Version 7.0 
Early Access was released. If you couldn't come by our booth 
and pick up a CD, you can purchase a CD for a small 
shipping cost. See our website. The CD contains our initial 
support for Mac OS X, which I'll cover in this article. But let's 
catch up on some recent happenings first. 

Recent Releases 

Code Warrior for Mac OS, Version 6.0 was released last 
year in which the IDE was carbonized along with other 
components. Since then, there have been two updates 
release. There hasn't been a Factory Floor article on Java for 
a long time so Til leave out those details and try to cover 
them in a future article. 

In January we shipped a Code Warrior Version 6,1 
Update, Included was an IDE 4,1.0,3 that contained a single 
bug fix to correct a problem where custom key bindings 
were sometimes forgotten. The update also contained a 
newer MetroNub Plugin that fixed a problem where AltiVec 
registers wouldn’t display correctly the first time you 


debugged your target. Lastly, the patch addressed some MSL 
problems. See the release notes for details: 

ftp://ftp.metrowerks.com/pub/updates/CWMacOS6/ 

6_1„Update_Re!ease_Notes.sit 

In May Metrowerks shipped a CodeWarrior Version 6.2 
Update. Although Version 6,0 was the last release to include 
68K support, the update included a newer C/C++ compiler and 
linker to fix some lingering bugs. Our front end compiler 
received a number of fixes also and a new version of the 
PowerPC compiler was released. Among the highlights in the 
compiler were support for greater than 32-bit bitfields, new 
scheduling support, pooling of floating point constants and 
support for a new .axp file that will prevent symbols from being 
exported. There are too many other improvements to list here, 
so be sure to check out the extensive release notes. (The URL 
for this wasn’t available when this article was submittedJ 

There And Back Again 

The biggest change in Mac OS X besides the rewriting of 
the Finder, is that PEF is no longer the preferred execution 
format for your code (despite the fact that this is what PEF 
stands for.) Mach-0 is the new kid on the block, having 
moved from Redwood City to Cupertino back in 1997. 

Mach-O is the native file format for storing executable 
code on Mac OS X that was developed for the defunct NeXT 
operating system. This is the equivalent of the l CODE f 
resource for 68K programming, and the PEF container for 
PowerPC development since System 7.1.2. The 'Mach' part 
comes from Mach 3A the microkernel that is the foundation 
of Mac OS X. If you want to develop natively for Mach-O you 
need a linker that can produce that format. 

Are there any compelling reasons to use Mach-O? Mac 
OS X still contains backward compatibility for Mac OS 9 in 
the form of support for CFM/PEF. If you carbonize your 
application appropriately using CodeWarrior Version 6,0 and 
use our PEF linker to write out your application, the 


Richard Alexander David Atwell, aka ratwell, collaborates on CodeWarrior development tools at Metrowerks and takes time out to keep fellow 
CodeWarriors informed About the world of Metrowerks, 
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application will siill work on Mac OS X bur it does so using 
a behind-the-scenes trick. 

When you launch a CFM/PEF application on Mac OS X 
using the Finder, it launches an application called 
LaunchCFMApp. This is a native Mach-O application that 
lives within the Carbon.framework folder (more on this 
later). What it does is take a path to a CFM/PEF application 
as an argument and builds a mini-CFM world for your 
application to live in, effectively hosting it for the life of your 
program. This helps to bridge the divide between your 
application and the Mach-O universe but it’s hardly ideal 
Your application will always launch slowly because 
LaunchCFMApp will have to launch first. 

Why didn't Apple combine CFM/PEF with the new 
kernel? Why are they requiring developers to “reformat" their 
applications in order to take ultimate advantage of the new 
OS? A similar question is why did they rewrite the venerable 
Finder? One reason probably has to do with the price of 
progress and the other development tools. 

The NeXT OS came with the ubiquitous UNIX GCC 
compiler and GOB debugger, and modifying those tools 
would mean adding support that wasn’t already available in 
the open source community. What about MPW? They were 
command line-like and supported CFM/PEF, but they've been 
in maintenance mode for several years and they didn't 
integrate with Project Builder and Interface Builder — 
Apple’s tools for rapid development using Cocoa. If you’ve 
been to Apple's developer site over the last two years, you’ve 
probably noticed that they’ve emphasized the importance of 
using Cocoa for developers wishing to write new 
applications for Mac OS X (Cocoa used to be called Yellow 
Box before Carbon was introduced.) In my own personal 
opinion, it was their drive to provide developers with a way 
to write new applications quickly that drove them to the 
decision to switch to Mach-O, But it's anyone guess. 

So here we are, just as we were in the days right before 
the PowerPC introduction, with a developer need for a 
toolset that embraces new Apple technologies. Where does 
CodeWarrior fit in? 

CodeWarrior for Mach-O 

You've got an application that you wrote with 
CodeWarrior a while back and need to bring it over to Mac 
OS X. It does everything your users want U to do but you've 
just discovered all the new APIs that Mac OS X provides in 
the /System/Library/Fra me works folder at the root of your 
Mac OS X volume. These frameworks are essentially folders 
that combine the header files you need to compile your 
application with the libraries the application will need to call 
at runtime. This is in contrast to the modern Mac OS 
programming model build you application against CFM stub 
libraries that we get from Apple and ship with CodeWarrior 
in the MacOS Support folder. 


Apple has provided CFBundle and CFPlugin into the 
CoreFoundation. framework to help CFM applications 
communicate with Mach-O binaries. But for those who need to 
truly take advantage of all the new APIs that Mac OS X provides, 
the choice is to rebuild your application as Mach-O. 

What CodeWarrior offers in this regard are updates to many 
of our components as well as a few new additions; a revised 
IDE and debugger, a new compiler and linker, an updated 
Powerplant and Constructor, and our MSL C++ Library. Let’s 
cover these each in depth. Hopefully not much will change 
since Pm writing this before w^e’ve completed everything for the 
WWDC Early Access CD, so consider this a true preview. 

IDE 

In CodeWarrior Version 6.0 we provided a carbonized IDE 
4,1 as a first step towards moving our toolset to Mac OS X, 
Beyond tweaking the interface for Aqua we've been upgrading 
the project engine within the IDE to support frameworks. The 
first due is a new fourth tab in your project window that 
appears when you are general ing a Mach-O binary. 



Figure L Project Window. 

The Frameworks tab organizes the 
/System/Library/Frameworks that you need to link your 
application against. In Figure I, Carbon refers to the 
Carbon.framework that exists on disk. Examine the 
framework and inside you'll see a symbolic link called 
Current that points to another folder that contains the current 
framework version. This version may be labeled A, B, C, etc, 
Apple can update the framework in a newer version of Mac 
OS X and leave the old version there so as not to break 
binary compatibility with your application if the changes they 
have lo make are radical The final version of the IDE will 
allow you to browse the headers that the framework contains 
as well as choosing the particular framework version you 
want to use. You’ll add frameworks by using the Add Files.,, 
item from the Project Menu to modify your project. 

Project Preferences 

My sample application is called “Application 11 . Let’s look 
at the target settings that you have control over. 
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Creating a Mach-0 target starts with the selection of a new 
tinker. The linker we're using is a CodeWarrior plug-in version 
of Apple's linker in much the same way that P PC Asm, our 
PowerPC assembler plug-in, is a repackaged version of the 
MPW tool with the same name. There is a Liblmport Mach-0 
plug-in for importing native libraries into our project format 
and for now a separate compiler plug-in for Mach-O which we 
might combine with the MW C/C++ PPG compiler in the future. 

What’s changed with the Access Paths that are usually 
setup for you by our stationery projects? 



Figure Access Paths 

The first thing to notice is that the Interpret DOS and 
Unix Paths checkbox is set. This feature is necessary in 
order to support frameworks. Look at this simple application 
that puts up an alert then quits. 

^include <Carbon/Carbon + h> 

emim 

[ 

UlertlD = 120 
); 

static void Initialize(void) 

t 

InitCursorO: 


int main[void) 
l 

InitializeO ; 


KoteAlert[kAlertID. NULL]; 
return D; 


Everything looks typical except the include' at the top. 
Instead of including MacTypes.h and its friends you ^include 
<Carbon/Carbon.h> instead, if you were building for some 
BSD Unix system a path like #include <sys/stath> would 
look normal; it would tell the compiler to look in the sys 
directory along the include path and find siat.h. On Mac OS 
X, because of its NeXT lineage, you won’t find a Carbon 
directory along the include path. Instead, the name before 
the / means look in the Carbon .framework directory along 
the include path. 

Look at the system include paths in our panel. The first 
two, msrdnclude and :usr:lib, are standard LInix include 
directories, In the first one you'll find files like stdio.h; in the 
second library files like crtl.o T the pre-installed C runtime 
library. The approach we’ve taken to adapting our MSL 
C/C++ implementation to Mach-0 has been to favor the 
buih-in support for the C library and provide our C++ 
implementation on top, because not all C++ libs are created 
equal and porting your code will be easiest this way. 

The third path points to our MacOS X support folder. 
This is a small folder compared to MacOS Support {even 
without the Universal folder) that contains our runtime 
sources and library along with a Mach-0 version of 
tMacHeaders, our precompiled header file. 
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WINNING WITH REALBASIC 
IS JUST THIS EASY. 


At REAL Software, we like it simple. Take our award-winning product, REALbasic, for 
example. People call it the powerful, easy-to-use tool for creating their own software for 
Macintosh, Mac OS X and Windows. We call it a problem solver. You've probably said, 
"Wouldn't it be great if there was a little application that...." REALbasic fills that blank. 

It's powerful and easy to use. Beginners and professionals alike can build software 
using a single, simple design. REALbasic compiles native applications for Macintosh, 
Mac OS X and Windows without requiring any platform-specific adjustments. Each 
version of your software looks and works just as it should in each environment. 

Experiment, explore, learn and innovate as you create anything from prototypes to 
complete professional quality applications step by step. Simply drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your 
stuff great — your ideas! 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 





REASONS A PRO LIKE YOU CAN GET LUCKY USING REALBASIC: 


1) It's compiled, not interpreted. Sure the name says "basic" but that's basic as in 
easy, not basic as in "ID GOTO ID 

That's not all. REALbasic compiles native applications for 68k, PowerPC and x86. Each 
Ul element for each platform is a native control for that platform, all created from a 
single project, requiring no platform specific code. 

2) REALbasic is extensible. By you — in a huge way. REALbasic sports a rich plug-in 
architecture, so you can add custom functionality using C and C++. Since all Mac 
developers love toolbox calls, we support access to them via declares. And we don't 
limit this only to the Mac — Win32 API calls are just as easy! 

3) Use REALbasic for prototyping. REALbasic handles all the details of III management 
for you. Want to see exactly how that new feature will really work? Whip it out in 
REALbasic! Of course, plenty of complete, commercial products rely on REALbasic for 
the whole project (not just prototyping), 

4) REALbasic is powerful. Extensive OOP technology is built right in. Stuff you know 
and love such as properties, classes and subclasses, methods and virtual methods, 
inheritance, interfaces, constructors and destructors and import and export of 
classes, modules and windows. 

5) It's loaded with Mac OS features. Everything you want and need is here, including 
AppleEvents and AppleScript, Balloon Help and Help Tags, Contextual Menus, Drag 
and Drop and QuickTime. 

See for yourself — download a free trial version today! 


O REALbasicB 


www.realbasic.com 






The last two point to framework directories on your Mac 
OS X volume. At last count, these two folders contained over 
13,000 files. As you can imagine when opening a project, our 
project engine goes for a bender trying to locate all the 
header and library files that your project is referencing, We’re 
working on a way to make the searching as efficient as 
possible due to this increase of header files. 

We aren’t providing these files like we do with the 
Universal folder within MacOS Support on our Tools CD, If 
you are still going to run CodeWarrior from Mac OS 9, you’ll 
either need to have these files available from your Mac OS X 
installation volume or copy them near to CodeWarrior. Either 
way, to allow the access paths to work correctly you’ll need 
to set up a Source Tree as seen in Figures 3 and 4. 


SourgeTrees 

We introduced Source Trees in CodeWarrior Version 5-0. 
Source Trees and allow you to create a custom reference 
point for your access paths. WcVe provided Source Trees for 
System, Compiler and Project for as far back as 1 can 
remember, so any path you make relative to those will allow 
you to distribute a project to others that will build correctly 
in their similarly set-up CodeWarrior environment. For 
Mach-0 development we’re requiring you to create a source 
tree called {OS X Volume}. When the latest IDE starts up for 
the first time, you’ll be prompted to create one and you can 
see the result when you open up the IDE Preferences. 



Figure 4 . Source Trees 

My source tree is called OS X Volume and points to my 
Mac OS X volume. If I had copied the files to my Mac OS 9 
Volume the source tree could simply point to the folder 1 
created there to hold the support files. There are target level 
source trees in addition to the global settings that every project 
inherits. You may elect to use the target level setting for 
distributing your projects but it’s easiest to use a global Setting. 

Target Settings 

Take a look at the PPC Mach-0 target panel Tills panel is 
enabled tor your project by the selection of the Apple linker. The 
first thing to notice is that there is an option to flatten resources. Tills 


is the preferred way to create resource files for Mac OS X, You can 
use this to output a non-iocalized resource File, such as MyApp.rsrc 
or localized ones for each language system you plan to support 
(more below on resources and folder layout). The MacOS Merge 
linker not shown here can also flatten resources. This is handy 
because you will be able to create targets and sub-targets to build 
and manage localized applications. 

So what kind of Mach-0 binaries can we produce? Look at the 
new project types: Application Bundle, Executable, Library, Object 
and Shared Library (these names might change in the final release). 


e ee Command Line jr. 


Command line: 

E r r "" 

Error Code: 0 


Results: 


PID TT SLAT TIME COMMAND 

49 7? Ss 0:22,07 /System/Ubr^/Framewcrks/ApplfcationSemcesTrar 

303 ?? Ss 1:08,47 /$y stem/Ub rary/Core Services/Win dowSe rver console 

304 T? Ss 0:04.13 /System/LJbrarY/CoreServices/loginwIndow.app/logfr 

309 ?? $ 0:02.83 /System/Llbrary/CoreServkes/pbs -psfL0_26214S 

310 ?7 $ 0:26.98 /System/Ubrary/CoreServices/Finderapp/Contems/K 

311 7? S 0:03.21 /System/IJbrary/CoreSemces/Dock.app/Coments/Nl, 

312 77 5 0:00.79 /System/Ubrary/CoreServices/DockHnoServerapp/Cc 


Figure 5* PPC Mach-0 Targel 


Bundle Up 

Mach-0 applications can load bundles to perform functions 
that CFM applications would load shared library plug-ins to do. 
Apple calls these “loadable bundles” because bundles are simply 
folders that collect tilings. Frameworks am bundles that contain 
headers and libraries. What visually distinguishes bundles from one 
another is the extension that is applied: .app for applications and 
their collective resources, .frameworks we’ve talked about already, 
.bundle tor generic bundles or .whatever you might decide upon for 
a loadable bundle. Other variants include .debug for debug versions 
of applications and .profile to applications that emit profiling data. 

Bundles use a directory layout to support multiple architectures. 
We've called these FAT for years on Mac OS. In NeXTStep and 
OpenStep they were called obese. Tf you want you can create a 
bundle that loads and executes a CFM app on Mac OS 9 and a 
Mach-0 version on Mac 05 X, The choice of binary is done by die 
OS and happens transparently to the user. 

Bundles can also be localized and globalized easily because of 
the layout. At runtime the OS looks for localized resources and picks 
the resources for the active script system. Bundles are also flat, 
meaning there are no resource forks so they am easily reside on 
LIPS, NFS and Win32 fileservers, whose file systems are flat by 
nature. Lastly, bundles can be moved around on disk as an atomic 
unit so items inside aren’t rearranged or lost by your users. 

An executable is exactly wfliat it describes: it corresponds 
to a traditional application with a filetype of APPLf You 
could use this to write a command line too! or write out an 
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application within an .app bundle. A stationery project is an 
effective way to setup an .app bundle layout instead of 
having the linker emit these files the first time it builds, 
Here’s an example folder layout for an application package 
called My App, app: 



vtyApp.app• 

9 items,83.0 MB avaiable 



Name 




Contents 


* 






CJ MacOS 



'■§ MyApp 


Pkglnfo 



Cj. Resources 




Cj Englishiproj 



B InfoPtet string 

A 

3 MyAppjsrc 

\ 



Ml* 




www.macosradio.net 

(a Mardun Software Ltd, company) 


Figure 6. Package Layout 

Packages appeared in Mac OS 9 in preparation for Mac 
OS X, Originally the bundle bit for the enclosing folder was 
reused to indicate a package but since then that method has 
been augmented to use the structure in Figure 6. Everything 
lives within the Contents folder and within that folder there 
are several items of note. The first is the Jnfo.plLst file which 
is like the Vers 1 resource from Mac OS. 


•Talk radio about the Mac, 
only on the Internet. 

•No more surfing to 100 
different sites to get your 
MacOS news. 


/’ Localized versions of Info.plist keys 7 
CFBundleNanie “ "HyApp"; 

CFBundleShortVersionString w "MyApp version 0 . 1 ”; 
CFBundleGetlnfoString = "MyApp version 0.1. Copyright 2001 
by Metrowerks. Inc + ”; 

Pkglnfo is the crucial file that decides whether or not the 
Finder will display the folder as a package. This is supported 
by Mac OS 9,1 in favor of the bundle bit. Its contents are 
even simpler. Be careful where you move the Pkglnfo file 
because if it's within a Contents folder it will turn the parent 
folder into a package. Mac OS 9 has a contextual menu 
option that lets you show/hide package contents, 

AFPL???? 

The last file, Info.plist, is required to describe the bundle 
in detail. IPs an XML file: 

<?xml version=*l .0* encoding =w IJTF-B”?) 

<[DQCTYPE plist SYSTEM 

"file://localhost/System/Library/DTDs/PropertyList.dtd“> 
<plist version="G.9”) 

<dict> 

<key>CFBundleDevelQpmentRegitm<7key> 

<string>English</string) 

<key>CFBtindleExecutahle</key> 

<String>MyApp</string) 

<key)CPBandleinfoDictionaryVersiorK/key) 

(string)6.0</string) 

<key>CFBundlePackag,eType</key> 
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The Keyspan Digital Media Remote is a powerful infrared remote 
which allows you to control multimedia applications on your 
computer in the same convenient way that you now control your 
home TV. Great for PowerPoint, QuickTime, DVD players, 

CD players, and MP3 Players! 
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haul a brick of a power adapter with you everywhere.' t his credit card 
sized power adapter makes your PowerBook truly mobile! Buy a second 
adapter for home! 
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haul a power adapter brick with you everywhere, but a second adapter for the office, 
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Power your iBook or PowerBook in a car or on a commercial airline 
flight. Forget swapping batteries, watch DVD after DVD on your 
next long drive or flight! 




West Ridge Designs introduces the "Macintosh inspired computer bag," the iBookBag. 
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<strin&>APPL</string) 

<key)C3?Bundle£ignature< /key) 

(string)????(/string) 

<key>CFBundleVersion</key> 

(string)Q.1</string) 

(/diet) 

</plist> 

Remember these are just sample file contents. See the 
extensive Apple document about these files using the URLs 
at the end of this article. 

More Target Settings 

Back to the Mach-0 Target Panel: die last three options 
are more easily described. Library is for generating a static 
library with the ,a extension, Shared Library is for dynamic 
libraries with the ,dylib extension. Typically dynamic 
libraries with this extension are designated so because they 
don't live within a framework. Dynamic libraries are loaded 
by dyld, the Mach-O loader equivalent of CFM. 

On Mac OS X t Mach-G dynamic libraries are lazily 
loaded. What this means is that symbols are resolved when 
functions in libraries are called instead of just when the 
application loads the library. The benefit of this is that code 
won't get loaded if the execution path of the program results 
in those functions not getting called. The downside is that 
this slows down the running of applications a bit. You can 
pre-bind your application to avoid this using our linker 
options but, as always, there is a trade-off. 

The last option is Object which is equivalent to the -r 
option you would pass to the command-line linker, Id. It’s not 
as useful as the others but you can learn more about it by typing 
" man Id” without the quotes from the Mac OS X Terminal.app. 

The next new panel is a variation on the PPC Processor 
Panel that is used for generating PEF applications. 



Figure 7. PPC CodeCen Mach-0 

Notice that die TOC options are gone because we are dealing 
with Mach-O. The Common Variables and Implicit Templates 
checkbox are new. The hist is a GCC-ism that prevents w T amings 
from appearing because a common variable is multiply-defined in 
several header files. The front end of our compiler has never liked 
this but if you are trying to compile axle that was previously built 


with GCC this option is useful. The second allows you to explicitly 
define which object files should have implementations of the 
template functions: another GCC-ism, 

The last panel is for the Mach-O linker and there’s a host 
of new options. I'll cover the ones that don’t also relate to 
the PEF linking. 



Figure & PPC Mach-0 Linker 

Emit Full Path in Stab Debug Info determines whether 
full pathnames are stored in the symbolics. You would 
typically disable this option so you could build your target 
on one machine then give your project to a friend to debug 
on another machine. Another use would be when you need 
to move iL from the folder where you built it to another 
folder in order to debug it. 

What is stabs? For PEF debugging, we generate a separate 
.xSYM file that contains the symbolic information that allows our 
debugger to map your source code to the binary file that our linker 
produced. The Apple Mach-0 linker generates stab symbolics the 
default way it is built, This is the standard symbolic file format that 
most Unix systems use. The GCC compiler generates it and the GDB 
debugger consumes it. Stab symbolics output is extremely verbose 
compared to xSYM. Unlike the separate file that is die case with 
xSYM, stabs is generated as a section of the output binary. To 
remove the stabs info from your debug application you can use the 
strip command-line tool but afterwards you won't l>e able to debug 
it. If you build your debug application as Mach-0 and all of a 
sudden it's gigantic, blame the stabs format. 

Emit Error on Multiple Symbols is an option to have the 
linker fail if multiple symbols are defined. The PEF linker 
generates a warning if you have symbols multiply-defined, 
but there is no option for failure. 

Pre-bind External Symbols avoids the lazy binding that the 
Mach-O loader perform on your application. Do this to speed 
up your application. There's probably a memory usage penalty 
for doing this but I’ve yet to completely experiment with it. 

Use Objective-C Semantics is used for loading all the 
classes and categories from static libraries. Objective-C 
programs are really meant as dynamic libraries. 

Current Version and Compatible Version tag dynamic 
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libraries so you can check programmatically whether or not to 
load a particular library. Zero is die default value and it means 
no checking. If a number other than zero is placed there it has 
an X[.Y.[Z]j] format where X is a number between 0 and 65535 
and Y and 2 are both between 0 and 255 and optional* 

Report Which Files Loaded produces output to the Error 
& Warnings window in the form of notes that tell you which 
object modules from w hich libraries were loaded in order to 
link your program, 

f usr/lib/libSystem.B . dylib (k_retn_pio2. o) 
i usr/lib/libSystem.B.dylib(cprocs.o) 
/usr/lib/UbSystera.B.dylibfisatty.oi 
/ iisr/ lib/libSysteiD.B *dylib (ungetc * a) 

Report Why Files Loaded is slightly more verbose in that 
it also tells you which symbols caused the library to load. 

/usr/lib/libSysteni.B.dylib[k_rem_pio2.o) loaded to resolve 
symbol: _kernel_rem_pio2 

/usr/lib/libSyfitem.B.dylib(cprocs.o) loaded to resolve symbol: 
_cproc_fork^child 

/usr/lib/libSysteauB,dylib(isatty.p) loaded to resolve symbol; 
_isatty 

/usr/lib/llbSysteni.B.dyliMungetc.o) loaded to resolve symbol: 
_ungetc 

Treat Read-Only Relocs as Errors/Wamings/Suppressed for 
Mach-0 is also a new option. To quote our compiler engineers, 
*ifs bad (for performance) to have relocations in a read-only 
data section, but it is supported. The user can select to generate 
an error and fail, generate a warning and continue, or do 
nothing and continue. Normally the compiler will not generate 
these Read-Only relocations, but there are some code 
generation situations that might cause tills to happen." 

That's it for the IDE and compilers. There's quite a bit that's 
new to consume but the stationery projects wall help you along. 

Debugger 

The hardest part of writing a debugger to support Mach-0 is 
having to support a new r symbolics format If youVe been to our 
website and seen the other products we sell ail of them have had 
one thing in common until recently: no support for stabs. We've 
been able to read DWARF, CodeView and of course xSYM for a 
number of years but we’ve never had a stabs reader to leverage for 
Mac OS X. Writing a stabs reader was a first step towards support 
for Mach-0 debugging. The fruit of tills labor is the StabSymbolics 
plugin that we'll ship in the CodeWarrior Plugins-Debugger: folder 
along with the SyinSymbolics plugin our debugger currently uses. 

While we were doing this we had to provide a debugging 
.solution for developers carbonizing their CFM/PEF applications for 
Mac OS X. At some point in the debugging process our debugger 
has to interact with the operating system to read/write memory, get 
register information and help to implement run control (step, run, 
stop). In addition, debuggers need to know when libraries load so 
debuggers can set breakpoints in them. To perform these tasks on 
Mac OS 9 we use our own code: the venerable MetruNub extension 
which was primarily written because Mac OS didn’t have robust 
enough debugger support built-in. Some debugging support 
appears in the PowerPC version of System 7 but at tine time we 


needed a debugger tliat supported 68K and PowerPC debugging 
equally. See MacTech Vol 13, A fa, 2 for the whole story. 

For Mac OS X, our debugger runs on top of GDB, If you’ve 
never used GDB before it uses a command line interface* If you’re 
used to CodeWarrior and not a hard core Unix person you may find 
it extremely difficult to use at first. When you use CodeWarrior to 
debug a PEF application, GDB is launching launchCFMApp behind 
the scenes and our debugger is reading the xSYM symbolics for your 
application and manipulating GDB which is providing the low level 
debugging. Sound complicated? All you see Ls the CodeWarrior 
interface as GDB is completely hidden behind die scenes. 

Our initial support for Mac OS X debugging was in die form of 
a remote debugging solution: Mac OS 9 ran the IDE anti Mae OS X 
ran the application being debugged. In the middle was an 
application called DebugNubController that passed messages hack 
and forth between die two systems over the network using TCP/IF, 
Having two machines wasn't ideal, so in CbdeWanior Version 6,0 we 
shipped an improved system that didn’t require two Macs, 
sometimes called local or single machine debugging dial we're all 
used to. Figuring out how to do this was tough up until a certain 
point because we had the same problem that other developers had: 
how to talk to Macb-O from a CFM application. We figured that out 
and now include a .bundle with CodeWarrior to let us interact with 
the Mach-O world ourselves. 

Writing a compiler is no small task but at least you can 
debug it on Mac OS 9. Since we use CodeWarrior every day to 
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write CodeWarrior, debugging the debugger on Mac OS X 
presented a classic bootstrapping problem and understandably 
we’ve been taking small steps debugging the debugger 
compared to the rest of the toolset. So w r here are we now? 

We've been working with Apple to provide a satisfactory Mac 
OS X debugging solution. This has included revising GDB many 
times to allow us to debug CFM applications better, especially those 
that load shared libraries. We'll continue to improve this over time. 
Now that we have a stabs reader, we’re working on die debugging 
of Mach-G applications. Check out our pre-release of this support 
w r hen it becomes available. 

MSL 

Not much to say about MSL except that our C++ 
implementation can run on top of the built-in C library. You’ll also 
notice that in the next release there will be no 6SK support. We 
made this decision based on your feedback and the fact that 
supporting 68K, PowerPC, Carbon and now Mach-0 is simply 
unnecessary these days as Apple hasn't shipped any 68k based 
hardware for a number of year’s now. The 68K tools work well, so 
just continue to use CodeWarrior Version 6,0 for any legacy 
development you need to continue. 


PowerPlant has undergone a number of improvements: 
fixes for drawing origin problems on Aqua, support for 
building with Universal Interfaces 3.4 and the latest Carbon 
SDKs, improved Carbon printing support, better support for 
Aqua and the biggest news is that the Appearance Classes 
moved out of the _In Progress folders. 

Next Time 

That’s my article about our official support for Mach-O 
in a nutshell, Mac OS X is a new beginning for users and 
developers alike. Get these tools at WWDC or contact us 
directly afterward and send us your feedback a.s.a.p. so we 
can make sure that CodeWarrior for Mac OS, Version 7.0 is a 
great release. 

If you’d like to get in touch with us about CodeWarrior 
Issues, post to our newsgroup or email us directly. Visit our 
website at www*metrowerks,com to learn more about us. 

URLs 

* http://developer.apple.com/techpubs/nnacosx/macosx.html 

* http://www.orel I lynet.com/mac/ 

* http;//wwwl .fatbrain.com/documentation/apple/ 


PowerPiant and Constructor 

PowerPlant is our popular application framework and 
Constructor is its companion UI design tool, For the early access 
release we updaLed Constructor to read and write flattened resource 
files. This is to allow' you to create your bundles more easily. 


Newsgroup: 
Technical Support: 
Report bugs: 
Suggestions: 


comp.sys.macprogrammer,codewarrlor 

cw_support@metrowerks.coni 

cw_bug@metrowerks.com 

cw_suggestion@metrowerks.com 

















Analysis 


One incredibly successful project manager. 

What does this guy know about software development that you don't? He knows that 
with FastTrack Schedule 7.0 hell shave hours off the time it takes to organize, track and 
manage the details of ail his development projects. And his eye-popping schedules are 
sure to turn heads and get results. 

Whether the project on tap is coding the next killer app or putting a fresh coat of paint 
on a client's website, FastTrack Schedule's three powerful views display your information 
the way you want—as a schedule, a calendar, or as a resource graph that tracks the 
people, equipment, and materials crucial to project success. 



And with our new compatible Palm OS version, you can sync schedules between your 
desktop and handheld. So even when you're on the run, your schedules are right at your 
fingertips. FastTrack Schedule also includes FastSteps™ intra-appiication scripting, full 
support for AppleScript, and is available in a compatible Windows version. For a free demo 
version or to order, call us today at 800.450.1983 or visit www.aecsoft.com. 

Easily the best in Project Scheduling! 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Moving Target 


Working with Wired Action Targets 


Introduction 

In the previous QuickTime Toolkit article, we got our 
first taste of working w ith wired actions. We attached some 
wired actions to sprites, first to construct a set of “movie 
controller” sprites, and then to make a sprite draggable. In 
both cases, we accomplished this by inserting one or more 
event atoms into the sprite atom and then inserting one or 
more action atoms into those event atoms. In several 
instances, we also inserted parameter atoms into the action 
atoms to specify additional information necessary for 
carrying out lhe action. 

In this article, we’re going to investigate wired action 
targets, which are the objects upon which wired actions are 
performed. Hitherto, we’ve relied on the fact that any action 
that has a target also has a default target, upon which the 
action will be performed if no object is explicitly targeted by 
that action. Here, well see how actions triggered by an event 
involving one sprite can be made to operate on another 
sprite, on another track, or indeed on a sprite or track in 
another movie. Along the way, well see how to set targets 
for operands and to add support in our applications for 
passing actions between movies. 

Our sample application this time around is called 
QTAct ion Targets; its Test menu is shown in Figure 1 . This first 
menu item creates a movie containing two sprites that target 
each other with actions. The second item adds a sprite track to 
an existing movie; this sprite track contains a single button that 
toggles the visibility state of the first text track in that movie. The 
next four items allow us to get and set movie names and IDs, 
which come into play when we want to send actions to external 
movies. The last menu item builds a sprite movie that can send 
actions to two external QuickTime VK movies at once. 


Tes 


Make Tiuin Sprites Mouie... 361 

fidd Te«t Toggle Sprite To Mouie 362 

Set Mouie Target Name... 363 

Show Motile Target Name 364 

Set Mouie Target ID... 365 

Shorn Mouie Target ID 366 

Make Dual DR Controller... 36? 


Figure 1: The Test menu of QTActionTargets 


Targets 

Most wired actions perform some operation on an element 
of a QuickTime movie; this element is called the action’s target. 
For instance, the kActionSprileTranslate action alters the matrix of 
a sprite so as to translate it horizontally and vertically by 
specified distances. As we noted in the previous article, each 
wired action has one particular type of target (if it has a target aL 
all, of course). QuickTime currently supports three basic kinds of 
targets: sprites, tracks, and movies. 

We specify an action's target by including an atom of type 
kActionTarget in the action atom. The target atom in turn includes 
one or more children that specify the kind of target and the 
method of specifying that target. As we’ll see, there are several 
ways to specify each kind of action target. 

If an action atom does not contain a target atom, then the 
action is sent to the default target. The default target for an action 
Lhat operates on a sprite is the sprite that contains the event atom 
that triggered the action. (Let’s call this the default sprite.) Frame- 
loaded events have no default spriLe, so sprite-related actions 
contained in a frame-loaded event s action atom must have an 
explicit target. On the other hand, idle events are sent to each 
sprite in a track, which is the default sprite for any sprite-related 
actions it contains. 

For track actions, the default target is the track that contains 
the default sprite (or, in the case of frame-loaded events, the 
track that contains die key frame). For movie actions, the default 
target is the movie that contains the default track. 


Tim Monroe works in Apple's QuickTime engineering group, You can contact him at monroe@apple.coni. 
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Targeting a Sprite 

We can specify a sprite target in one of three ways: by 
name, by ID, or by index. The file Movies.h defines these 
constants for specifying a sprite target type: 

enrnn [ 

kTargetSpriteName = FQUR_CHAR_CODE(* spna'), 

kTargetSprit elD = FQUR_CHAR_CODE( + spid' ) * 

kTargetSpritfelndex ** FOUR_CHAR_CODEPapin 1 ) 

When we target a sprite by name, QuickTime looks at each 
sprite atom in the target track for a child atom of type 
kSpriteNameAtomType. Lf it finds an atom of this type, it inspects 
the atom data to see whether it's identical to the name specified 
in the kTargetSpriteName atom. If it is, that sprite becomes the 
target sprite. If no sprite in the target track has the correct name, 
die action is not performed. 

In general, I prefer to target sprites by ID, largely because we 
haven’t bothered to name our sprites and because the sprite index 
depends on the order we insert sprites into the sprite track. Listing 
1 shows one of die wared sprite utility functions. 
WiredUtils^AddSpritelDActionTargetAtom. which we can use to build 
a sprite ID target atom and insert it into a given action atom. 

List ing Is Targeting a sp rite by fl>_ 

WirtdUtitejVddSpritt'mAetionl^r^etAtom 

OSErr WiredUtils_AddSpriteIDActionTatgetAtom 

(QTAtomCotttainer tbeContainer ( QTAtom theActionAtom, 
QTAtomlD the Sprite ID, QTAtom *thelfewTargetAt0ni) 

i 

QTAtom myTargetAtom = 0; 

OSErr myErr “ noErr; 

if CtheNewTargetAtom != NULL) 

*theNevTargelAt(jrn = 0: 


myTargetAtom = QTFin.dChildByIndex (tbeContainer* 

theActionAtotn, kActionTarget, 1 , NULL); 
if {myTargetAtom — Q) I 

myErr = QTIneertChild{tbeContainer* theActionAtom, 
kAetionTarget, 1, 1, 0, NULL, 

&myTargetAtom): 
if (myErr != noErr) 
goto bail: 

I 

theSpritelD * EndianU32_NtoB(theSpritelD) ; 
myErr = QTIneertCh.ild[theContainer. myTargetAtom, 
kTargetSpritelD, 1, 1, 
sizeof(theSpritelD), StheSpritelD, NULL): 

bail: 

if (theNewTargetAtom 1= NULL) 

*theNewTargetAtom “ myTargetAtom; 
return(myErr); 


WiredUtils^AddSpritelDAotfonTargetAtom starts off by looking 
for an existing target atom in the specified action atom. If none 
is found, it adds a target atom. In either case, it then inserts a 
child of type kTargetSpritelD into the target atom, setting die atom 
data to the sprite ID we pass in (suitably converted to big-endian 
form, of course). 

Let’s use WiredUtiJs_AddSpntelDActionTargetAtom to build a 
movie in which two sprites target each other. Figure 2 shows 
the movie we want to build; clicking on one sprite rotates the 
other sprite 90 c clockwise. (In Figure 2, we’ve clicked on the 
left-hand sprite once.) 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
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Figure 2: Two sprites targeting each other 


We construct this movie in the standard way, creating a 
sprite track and media and then adding sprite images and 
samples to the media. Listing 2 shows the code we use to add 
actions to the left-hand sprite (which has ID 1). 


if (theNewTargetAtom != NULL) 

*theNewTargetAtora = 0; 

myTargetAtom " QTFindCMldBylndex (theContainer, 

theActionAtom, kActionTarget, 1, NULL); 

if (myTargetAtom — 0) \ 

myErr =* QTInsertChild(theContainer. theActionAtom* 
kActionTarget* 1* 1. Q* NULL, 

SimyTargetAtom); 
if {myErr ]” noErr) 
goto bail; 

I 

myErr ■ QTlnsertChild(theContainer, myTargetAtom, 

kTargetTraekName. 1, 1. theTrackNamefQ] + 1, 
theT r a c kName * NULL); 

bail: 

if (theNewTargetAtom != NULL) 

•theNewTargetAtom = myTargetAtom: 

return(myErr); 



QTTarg_AiM[con MovicSamp Jcslt >Media 


Wired UtiIs_AddGTEv e nt And Ac tionA t oms(my S p rit e Da ta. 
kParentAtomlsContainer, 
kQTEventMouseClickEndTrigge rButton. 
kActionSpriteRotate* fonyActionAtotn): 

myDegrees = EndianS32_NtoB(FixRatio(90, 1)): 

WiredUtils_AddAc tionFarameterAtom (my Sp riteData, myActionAtotn< 
kFirstParam, sizeof(myDegrees). imyDegrees. NULL): 

WlredUtils^AddSpritelDActionTargetAtoroCmySpriteData, 
myActionAtom. 2, NULL); 


We wire the right-hand sprite in exactly the same way, 
substituting target ID 1 for 2 in the fast line of code. 


Targeting a Track 

We can specify a target track in one of four ways: by name, 
by ID, by index, or by index of a particular type. That is, we can 
look for the second track in a movie, say, or Lhe second video 
track in that movie. Movies.h defines these constants for 
Specifying track target types; 


enum t 

kTargetTraekName 

kTargetTracklD 

kTargetTrackType 

kTargetTracklndex 

1; 


F0UR_CRAR_C0DE{‘trna K ), 

- FGUR_CHAR_CGDE( 1 trid 1 )* 
FOUtLCHAJLCGDE(* t rty f ), 

- F0UR_CHAR_C0DE (' 1 1 in’) 


To specify a target by index of a type, we include both 
kTargetTrackType and kTargetTracklndex atoms in the target atom, 
Once again, well want to define some utilities to facilitate 
creating track targets. Listing 3 defines the 
WiredUtils_AddTrackNameActionTargetAtom function, which sets a 
track target, given a name. 

Listing 3: Targeting a track by name 

Wircdl Jtils_AddTrackNameAaionTargetAtom 

OSErr WiredUtiis_AddTrackNameActionTargetAtQlfl 

(QTAtomContainer thaCoutainer* QTAtom theActionAtom* 
Str255 theTrackName. GTAtom 'theNewTargetAtom) 
t 

QTAtom myTargetAtom = 0: 

GSErr myErr = noErr: 


Listing 4 defines a more general function, 
WiredUtils_AddTrackTargetAtom, which calls 

WiredUtils_AddTrackNameActionTargetAtom and two other utilities 
(which we won t show here). Notice that if theTrackTargetType is 
kTargetTrackType and theTracklype Index is non-zero, then 
WiredUtils_AddTrackTargetAtom inserts two target type atoms, as 
we mentioned above. 

Listing 4: Targeting a track 

Wiredtltils_AddTrackT 3 rgc j L\tom 


OSErr WiredUtiis_AddTrackTargetAtom 

(QTAtomContainer theContainer, QTAtom theActionAtom* 
long theTrackTargetType, void *theTrackTarget H 
long theTrackTypeIndex) 

I 

OSErr myErr w noErr; 

// allow xe to for the default target (the sprite track that received the event) 

if (theTrackTargetType !“ 0) l 
switch (theTrackTargetType) I 
case kTargetTrackName: ( 

StringFtr myTrackName “ (StringFtr)thaTrackTarget: 

myErr = WiredUtils^AddTrackNaineActionTargetAtom 
(theContainer, theActionAtom, myTrackName. NULL): 
break; 


case kTargetTracklD: 1 

long myTrackID = (long)theTrackTarget: 

myErr = WiredUtils_AddTrackIDActionTargetAtom 
(theContainer, theActionAtom, myTracklD* NULL); 
break; 


case kTargetTrackType: I 

OSType myTrackType = (long)theTracklarget: 

myErr = WiredUtils_AddTrackTypeActionTargetAtom 
(theContainer. theActionAtom. myTrackType, NULL): 
if (myErr 1= noErr) 
goto bail: 

if (theTrackTypeIndex != 0) 

myErr = WiredUtils_AddTrackIndexActionTargetAtom 
(theContainer. theActionAtom, theTrackTypeIndex* 

N ULL ); 
break; 
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c as e kTa r getTrac klnd ex: [ 

long myTracklndex = (long)theTtackTarget; 

myErr = WiredUtil£_AddTrackIndexActionTai:getAtam 
(theCoutainer, theActionAtom. myTrack Index. NULL); 
break: 

1 

default; 

niyErr = paramErr; 

1 

1 

bail; 

return(myErr): 

1 

To illustrate how to target a track, we'll create a sprite 
button that enables or disables the first text track in the 
movie. Figure 5 shows this button located in the upper-left 
corner of the movie; clicking it disables (and thus hides) the 
first texL track in the movie, and clicking it again re-enables 
(and thus re-shows) that track. 


□ in penguin.moll m S 



70% 


Figure 3: A sprite button that targets a text track 


Lei's see how to wire the sprite to achieve this behavior. 
First, we want to change the sprite image on mouse-down and 
mouse-up events, like this; 

WiredUtils_AddSpriteSetImageIndexAction(inyTextEutton. 

kParentAtomlsContainer. kQTEventMauseClick. 0, NULL. 

0, 0, NULL, kTextftovnlndex. NULL): 

Wir e d Ut i 1 s_AddSp rite Set Ima ge I n d e xA c ti on (utyTextButton, 

kFarentAtomlsContainer, kQTEvent Mo used i ckEnd, 0* NULL. 

0, 0, NULL. kTextUpIndex, NULL): 

Next, we w r ant to attach some track enabling and disabling logic 
to the button. Here we have several possibilities. We could read 
the value of the kOperandTrackEnabled operand to determine 
whether the text track is currently enabled or disabled and then 
call kActionTrackSetEnabled with false or true, accordingly. Or, 
much more simply, we can add an action atom of type 


kActbnTrackSetEnabled and then set that atom's action flags to 
toggle the value of the track's enabled state: 

Wir e d Uti1s_Ad d QTEven tAndAc tionAt oms(myTextButton, 
kPa r en t At oml sC on t a i n e r, 
kQTEv entHo us e CllckEn dTriggerlutton r 
kActionTrackSetEnabled. &myActionAtom) : 

WiredUtils_AddActionPa ranete rOptions(inyText Button. 

myActionAtom, 1* kActionFlagActionlsToggle. 0. NULL, 0, 
NULL); 

We specify' action flags by inserting an atom of type 
kActionFlags into the action atom. The atom ID should be the 
same as the ID of a parameter atom in that action atom, and the 
atom data is a big-endian long integer that has one or more of 
these Hags set: 

enum i 

kActiouflagActionlsDeLta “ 1L « 1* 

kActlauFlagParaineterWrapsAroLmd = 1L « 2* 

kActionFlagActionlsToggle = IL « 3 

h 

The flag k ActionFlag Action IsDelta indicates that the value of 
the corresponding parameter atom is a relative value, not an 
absolute value. The Hag k ActionFlag ParameterWrapsAround 
indicates that a value that exceeds the maximum possible 
value of the parameter is automatically set to the minimum 
value (and similarly for values that are less than the 
minimum value). We set a parameter’s minimum and 
maximum values by inserting atoms of type 
kActionParameterMinValue and kActlonParameterMaxValue into 
the action atom. The Hag k ActionFlag Action IsToggle indicates 
that the parameter value should be toggled between two 
possible states. In this case, the actual value specified in the 
parameter atom is ignored. As a result, we haven’t bothered 
to actually add a parameter atom to the 
kActionTrackSetEnabfed action atom. 

Finally, we call WiredUtils_AddTrackTargetAtom to set the 
sprite action’s target to the first text track in the movie, like this: 

WiredUtils_AddTracfcTargetAtom[myTextEuttoo. myActionAtom, 
kTargetTrackType. (void ‘)TextMediaType, 1); 

Movie-to-Movie Communication 

Now we have a good idea of how to target specific sprites 
and tracks in a movie. One of the neat additions in QuickTime 
4.0 was the ability also to target external movies. That is to say, 
evenLs related to a sprite in one movie are able to trigger actions 
that operate on a sprite or track or movie property in another 
movie. This ability is called movie-to-movie communication or 
intermovie communication. In this section, well see how to 
target elements of external movies. On one level, this is a very 
simple thing to do, as it's just another exercise in adding target 
atoms to action atoms. Il turns out, however, that the movie 
controller needs help resolving target atoms when they pick out 
external movies. As a result, well need to add some code to 
QTActionTargets to allow jL to route actions from one open 
movie to another. This is a somewhat more complicated 
undertaking, so let’s proceed carefully. 
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Adding External Movie Targets 

First, the easy stuff. We can specify an external movie target 
in one of two ways; by name or by ID. The file Movies.h defines 
these two constants for specifying a movie target type: 

enuin ( 

kTa r ge t Mo vieName “ FQU R_CHAR_CODE(*mona'}, 

kTargetMovielD “ FOUE_CHAK_CODE f'moid') 

h 

To target an action at an object in an external movie 
specified by name, for instance, we add an atom of type 
klargetMovieName to the action atom. The target atom data is the 
movie's target name, stored as a Pascal string. Listing 5 shows 
the function WiredUtils.AddIVIovieNameActionTargetAtom, which 
we can use to add the appropriate target atom to an action atom. 


listing 5: Targeting a movie by name 

Wi redll I ib_Adcf MovieName Act ioiiTargerAtom 

GSE it WiredUtils_AddMovieNameActianTargetAtom 

(QTAtomContfliner theContainer. QTAtont theActionAtam f 
Str255 theMovieName* QTAtom *theNewTargetAtom) 

{ 

QTAtom mylargetAtom = 0; 

OSErr myErr * noErr; 

if CtheNewTargetAtom I * NULL) 

*theNevTar getAtom “ 0; 

myTargetAtora = QTFindChiIdBylndex(theContainer. 

theActionAtom. kActlonTarget, 1. NULL); 
if (jnyTargetAtom — 0) \ 

myErr = QTInsertChild(theContainer H theActionAtom, 

kActionTarget. 1, 1< 0, NULL, GcmyTargetAtom); 
if (myErr ]■ noErr) 
goto bail: 

[ 

myErr = QTInsertChild(theContainer t mylargetAtom* 

kTargatMovieName. 1 T 1. theMovieName[0] + 1, 
theMovleNarae, NULL); 

bail: 

if {theNewTargetAtom J* NULL) 

•thoNewTargetAtom “ myTargetAtom: 
return(myErr): 

} 


The function WiredUti[s_AddMovielDActionTargetAtom (not 
shown here} is entirely analogous, except that the target atom 
data is a signed long integer specifying the target movie’s ID. 


Specifying Movie Target Names and IDs 

So how do we specify a movie’s target name or ID? The 
movie target name is not the name of the movie file that it’s 
contained in (which is good, since some movies exist only in 
memory or only as a network stream). Rather, the movie 
target name or ID is stored as a piece of movie user data of 
type plug . To specify a movie's target name, we add a piece 
of movie user data of type l piug' whose item data is a string 
of characters of this form: 

moviename=” name H 

And to specify a movie’s target ID, we add a piece of movie 
user data of type plug’ whose item data is a string of 


characters of this form: 

I^Qvield="fD ,, 

User data of type plug 1 was introduced originally for use 
by the QuickTime web browser plug-in, for storing 
parameters for movies embedded in web pages. For instance, 
to hide the movie controller bar of an embedded movie, we 
can attach a piece of plug' user data to the movie whose item 
data is this string of characters: 

CONTROLLER-*Fala e " 

Similarly, we can make a web-based movie loop during 
playback by attaching a piece of 'plug' user data with this data: 

LOOF=”True" 

(QuickTime Flayer ignores all user data items of type plug' 
except for moviename and movieid.) 

The data in a user data item of type plug 1 consists of a tag, 
the equality* sign (=), and a value that is enclosed in quotation 
marks (“X (In fact, the quotation marks are optional, but they're 
highly recommended.) The tag and value are strings of 
characters; case does not matter in these strings, so “moviename ' 
is treated the same as “MOVIENAME" (or as any of the other 510 
possibilities). In our code, well always create all lowercase lags, 
using these constants: 

# define klio vi eNameP re fix "movie ns me= H ’ 

^define kMovielDPrefix "movieid**" 
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Listing 6 defines the function QTUtils_SetMovieTargetName. 
which we can use ro attach a specific target name to a movie* 
The meat of this function consists of concatenating the prefix 
kMovieNamePrefix, a quotation mark, the specified target name, 
and a terminating quotation mark into a single string, which we 
set as the user item data. 


Listing 6; Se tting a movie’ s target name 

QTUtils_SctMovicTargetName 

GSErr GTUtils_EetMovieTargetNarae 

(Movie theMovie, c±ar ‘theTargetNaJne) 

l 

UserData myUserData “ NULL; 

char *jny5tring “ NULL; 

Handle ^Handle - NULL; 

OSErr myErr = noErr; 

// make sure we've got a movie and a name 
if ((theMovie = NULL) || (theTargetName = NULL)) 
return(paramErr); 

// get the movie's user daia list 

myUserData - GetMovieUserData(theMovie): 
if (myUeerData = NULL) 
return(paramErr); 

// remove any existing movie lurgei name 

while (OTJtils_FindUserOatalT^WithPreflx (myUserData, 

FOtJR_GHAR_CGDE ( 1 plug ’) * kMovieNa me Prefix) t= 0) 

RemoveUserData(myUserData, FOUR_CHM_CODE(‘plug"), 

QTUtils_FindUserDetaItemWithPrefiK(rayUserUata. 
FOIiK_CtlAR_CODE [ 1 plug 1 3 , kHovieNamePrefix)) : 


// create the user data Item daia 

myString = malice(strlenfkMovieNamePrefix) + 

strlen{theTargetWame) +2 + 1); 
if (rayString 1“ NULL) { 
myString[0] = *\G* : 
street( mySt ring * kMovieNamePrefix); 
street(myString, M \); 
streat(myString, theTar get Name 5: 
st reat (my String, “\ HM ); 

// add in a new user data item 

FitToHand(rayString, fanyHandle. strlen(myString)) t 
if [myHandle 1= NULL) 

myErr = AddUserData(myUserData. myHandle, 
FOUILCHARCODE(* plug 1 ')); 

J else { 

rayErr - meraFullErr: 


free(myString); 

if (myHandle 3° NULL) 
DisposeHandle(myHandle); 

return (inyErr); 

} 


Notice that QTUti3s_SetMovieTargetName first removes any 
existing movie target name user items hy repeatedly calling 
QTdtils.FindUserDataltemWithPrefix and RemoveUserData. 
QTUtils_FindUserData!temWith Prefix is defined in Listing 7, It 
simply inspects all user data items of a specified type to see 
whether any of them begins with the specified string. When 
the first matching item is found, the index of that item is 
returned to the caller. 
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listing 7; Finding a use r data item _ 

QTUtiisFimlL ;serDatil lemWithFrefix 

static long QTUtilsJTindUserDataltemWithPrefix 

(UserData theUserData* OSType theType. char *theFrefix) 

I 

Handle myData = NULL: 

long myCount = 0: 

long mylndex = 0: 

long myltemlndex = 0: 

OSErr myErr = noErr; 

// make sure we’ve got some valid user data 
if (the User Data = NULL) 
goto bail: 

// allocate a handle for GetUserData 

myData = NewHandle(O); 
if (myData — NULL) 
goto bail: 

myCount ~ CountUserDataType(theUserData, theType): 
for (mylndex = 1: mylndex <- myCount: mylndex+t) \ 
myErr = GetUserDataftheUserData. myData, theType, 
mylndex); 

if (myErr noErr) I 

if (GetHandleSize(myData) ( strlen{thePrefix)) 
continue; 

// see if the user data begins with the specified prefix 

if (IdenticaIText('myData, thePrefix. 

strlen(thePrefix), strlen(thePrefix)* NULL) = 0) ! 
myIremindex = mylndex: 
goto bail: 

] 

1 

) 

bail: 

if (myData != NULL) 

DisposeHandle(myData); 

return(myltemlndex); 

1 

IdenticalText (ne lUMagIDPString) is a Texi Utilities function 
that compares two strings to see whether they are identical; it is 
case-iasensitive and ignores any diacritical marks (such as the 
accent in u ne*). 


Retrieving Movie Target Names and IDs 

We know how to set a movie’s taiget name or ID, so that 
actions in other movies can he targeted at it. Let's now see how¬ 
to get a movie’s taiget name or ID. The basic idea is simple 
enough: just loop through all user data items of type plug' until 
we find one that begins with either kMovieNamePrefix or 
kMovielDPrefix; then extract the value of that user data item, 
Listing 8 shows the QTUti]s_GetMovieTargetName function. 
(GTUtiis_GetlVfovieTargetlD is entirely analogous, except that it 
also returns a Boolean value dial indicates whether the specified 
movie actually has a movie target ID.) 

Listing 8: Getting a movie’s target name 

QlTiLils_GeLMovfeTargetName 

char *QTUtilBjSetMovleTargetName (Movie theMovie) 

I 

UserData myUserData - NULL: 
char 'myString “ NULL: 

// make sure weVe got a movie 

if (theMovie = NULL) 


goto bull; 

// get the movie’s user data list 
myUserData = GetMovieUserData(theMovie): 
if (myUserData = NULL) 
goto bail; 

// find the value of the user data item of type ‘plug’ that begins with 
// the string * mo vfcname^ 

myString = QTUtils_GetUserDataFrefixedValue(myUserData. 

FOUR_CHAR_COD£(‘plug 1 ), kMovieNamePrefix); 

bail: 

return(myString); 

J 

As you can see, GTUtils_GetMovieTargetName calls 
QTUtils_GetUserDataPrefixedValue, defined in Listing 9- 
GTUtils_GetUserDalaPrefixedValue calls 

QTUttls^FindUserDataltemWitliPrefix to find the index of the 'plug 
user data item that begins w r ith the specified prefix. If it finds 
one T then it returns the value in the item’s data, making sure to 
strip off any quotation marks surrounding the value. 


Listing 9: Getting a user data item value_ 

QTl 1 [ib_GcilJserDataPrefixcd Value 

static char 'QTUtils^GetUserDataPrefixedValue 

(UserData theUserData* OSType theType* char *theFrefix) 

f 

long mylndex ” 0; 

Handle myData = NULL; 

long myLength ” 0: 

long myOffset ■ 0: 

char 'myString 15 NULL: 

OSErr myErr = noErr; 

if (theUserData = NULL) 
goto bail: 

// allocate a handle tor GetUserData 

myData " NewHandle(O): 
if (myData = NULL) 
goto bail: 

mylndex " QTUtils_FindUserDataIteroWithFrefix(theUserData* 
theType* thePrefix): 

if (mylndex > 0) [ 

myErr “ GetUserData[theUserData. myData, theType, 
mylndex): 

if (myErr = noErr) { 

if (('myData) [strlen(thePrefix)1 = ’"’) ( 
myLength w GetHandleSize(myData) - 

strien(theFrefix) - 2: 

myOffset = 1; 

) else I 

myLength = GetHandleSize(myData) - strlen(theFrefix); 
myOffset = 0; 

\ 

myString = maHoc (myLength + 1): 
if (myString 1” NULL) I 

memepy(myString. 'myData + strlen(thePrefix) + 
myOffset. myLength): 
myString[myLength] = '\0*; 

1 

1 

l 

bail* 

if (myData l- NULL) 

DisposeHandle(myData); 

return(myString): 

) 
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Finding Movie Targets 

Remember that we don't just want our applications to be 
able to create wired actions with external movie targets, but we 
also want them to be able to play those movies back correctly, 
routing actions to the appropriate external targets. This raises a 
complication: although a movie controller is able to Find target 
sprites and tracks inside of the movie ifs associated with, it isn't 
able to Find targets in external movies. For that, it needs help 
from the application. 

When a movie controller determines that it needs to find an 
external movie target for some wired action, it sends itself the 
mcActlonGetExternalMowe movie controller action. The idea is 
that the application will intercept that action in its movie 
controller action filter function, find the specified target movie, 
and return information about that movie to the movie controller. 
Let’s see how QTActionTargets handles all this. 

When our movie controller action filter function receives 
the mcActionGetExlernalMovie action, the First parameter is the 
movie controller issuing the action and the third parameter is a 
pointer to an external movie record , of type 
QTGetExtemaJMovieRecord: 

struct OTGetExternalMovieRecord { 
long targetType: 

StringPtr movieName; 

long movielD: 

KoyiePtr theMovie; 

MovieControilerPtr theController: 
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1: 


The targetType field specifies the kind of target that the movie 
controller wants information about; on entry to our movie 
controller action filter function, its set to either 
kTargetMovieName or kTargetMovielD. If targetType is 
kTargetMovieName, then the movieName field specifies the name 
of the movie to look for. If targetType is kTargetMovielD, then the 
movielD field specifies the ID of the movie to look for. 

Our job is to find the target movie and return both it and its 
associated movie controller in the theMovie and theController 
fields of die external movie record. If we cannot find the target 
movie, then we should set both theMovie and theController to 
NULL. Listing 10 shows die movie controller action filter function 
in QTActionTargets. 


case mcActionldle: 

QTApp_Idle({**myWindavObjectl.fWindow); 
break; 

// handle gei-extemaJ-movie requests 

case me Ac 11 duG etExt e r nalMovie: 

QTF r a me_FindE* t e r na IMo v ieTa r ge t(th eMC > 

(QTGetExtersalMoviePtr) tbePararas); 

break: 

//some lines missing here: see Listings 13 and 14 

default: 
break: 

| ft switch (theAction) 
return(isHandled): 


Listin g 10: Handling movie controller actions 

QTAp p_MCAc tionFiJ t e rP roc 

FASCAL_RTN Boolean QTApp_MCActiaaFilterProc 

(MovleControiler theMC, short theActlon, void ‘theParams. 
long theRefCon) 

[ 

Boolean isHandled = false; 

WindowQbject myWLndowObjeet = NULL;; 


As you can see, when we receive an mcActionGetExter nalMovie 
action, we call the application-defined function 
GTFrame^ Fi nd Exte rna] Movi eTarget , It loops through all open movie 
windows belonging to our application and (depending on die value 
of die targetType field) looks for a movie having the correct name 
or ID. GTFrame^FindExternalMovieTarget is defined in Listing IT 


myWindowQbject = (WlndouOhject)theRefCon; 
if (myWind ovObje ct = NULL) 
return(isHandled); 

switch (theActlon) 1 

// handle window resizing 

case meActionControllerSizeChanged; 

QTFrame JSiseWindowToMovie{myWindowObj ect): 
break: 

// handle idle events 


Listing Mi Findin g a target movie _ _ _ 

QTFrame_FiiMlExternalMovieTarget 


void QTFrame_ FindExternalMovieTarg.et 

(MovieController theMC, QTGetExternalMoviePtr theMRecPtr) 

{ 


Wind owRe fe r enc e 
Movie 

MovieController 
Boolean 


myWindow = NULL: 
myTargetMovie = NULL: 
nryTatgetMC = NULL; 
myFoundlt = false: 
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if (theEMRecPtr = HULL) 
return; 

// loop through all open movies until we find die one requested 
myWin d ov = QTF r ame_Get Fron tMo vieWindow(]; 
while (myWindow != NULL) I 

Movie my Mo vie = NULL; 

Movie Controller myMC “ NULL; 

myMC = QTFtame_GetMCFrotnWindow(rayWindov); 

Hf ALLOW_SELF_TMGETING 
if (myMC != NULL) ( 

#else 

if ((myMC t- NULL) && (myMC t= theMC)) [ 
tfendif 

myMovie = MCGetMovie(myMC); 

if (theEMRecPtrOtargetType = kTargetMovieNante) ( 
char *myStr = NULL; 

myStr - QTUtils_&eiiMGvieTargetName (myMovie); 
if (myStr != NULL) l 

if (IdenticalText(StheEMRecPtr->movieName[I]. 
rayStr, theEMRecPtr■>raovieName[0] , 
BtrlenfmyStr). NULL) = 0) 
myFoundlt = true; 
free(myStr); 

I 

l 


if (theEMRecPtr->targetType = kTargetMovielD) \ 
long mylD = 0t 

Boolean myMovieHasID = false; 


I 


my ID = QTUtila_GetMovieTargetID(rayMovie. 

fidnyMovieHasID); 

if ((theEMRecPtr->movieID = myID) && 

myMovieJlaslD) 


myFoundIt = true: 
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if (myFoundlt) t 

myTargetMovie = myMovie: 
myTargetMC “ myMC; 
break: //break out of while loop 

i 

] 

myWindow = QTFrsme_GetNextMovieWindow(myWindow); 
\ // while 

* t h eEMRec Pt r-> t heMovie = myTargetMovie; 
'theEMReoPtr->theController " myTargetMC; 


QTFrame_FindExtemalMovieTarget uses our framework 
functions OTFrame_GetFrontlVlovieW indow and 

QTFrame.GetNextMoviaWindow to loop through the open 
movie windows; it also uses the QTActionTargets functions 
GTUtils_GetMovieTargetNama and QTUtils_GetMovieTargetlD to 
find the target name or ID of the movie in each of those 
windows, (These latter two functions are defined in the file 
GTActionTargets.G, but they are generally useful and should 
migrate to QTUtilitres.c.) 

There is one interesting question we need to consider: 
should a movie be allowed to target itself using external 
movie targets? That is to say, when we attach a target atom 
of type kTargetMovieName or kTargetMovielD to some wired 
action, should we allow the targeted movie to be the same 
movie that contains that wired action? On one hand, 
targeting oneself using movie targets is outrageously 
inefficient; the movie controller needs to call the 
application’s movie controller action filter function, and the 
application needs to go looking at the user data of all open 
movie windows (at least until it finds the targeted movie). If 
our goal is to target the movie that contains the action, we’re 
better off just omitting any movie target atom from that 
action and thus using the defaulL movie target. On the other 
hand, we might think; “why not allow it?” Alter all, a target 
ID might be obtained dynamically by evaluating some 
expression, which (as it happens at run time) picks out the 
very movie that contains the wired action container. As long 
as we’re clever about it, efficiency should not be a real 
problem. And no doubt some interesting effects can be 
achieved if we allow self-targeting, 

Personally, I'm inclined to think that a movie should be 
able to target itself. Unfortunately, QuickTime Player seems 
to think differently; it does not currently al!ow r wired actions 
to target objects in the same movie using an explicit movie 
target. So I've written QTFrame_FindExternaIMovieTarget to 
provide either capability, depending on the setting of the 
compiler Hag ALLOW_SELF_TARGETING. You decide how 
you wanL your application to behave. 

Controlling External Movies 

Let’s build a movie with some sprites that target an external 
movie, In fact, let's build a movie with some sprites that target 
two external movies at the same time. Figure 4 illustrates what 
1 want to achieve. This is a web browser window that contains 
two QuickTime VR panorama movies and a sprite movie, lire 
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top movie is a panorama of the Dormer Lake area (in California) 
shot during the summer The bottom movie is a panorama of the 
same area shot during the winter Each of these panoramas can 
be individually controlled in the standard ways (for example, 
panned left or right by dragging the cursor horizontally)* But 
these panoramas can also be controlled in tandem using the 
middle movie, which is a sprite movie containing six sprites. 



Figure 4: A sprite movie controlling two QuickTime VR movies 

This sprite movie consists of a single sprite track with buttons 
that perform these actions (from left to right): pan left, tilt down, 
zoom out, zoom in, lilt up. and pan right The VR controller 
sprite track is constructed in exactly the same way as the linear 
controller sprite track we built in the previous QuickTime Toolkit 
article, except that the sprite images are different and the actions 
issued by each button are VR actions (for instance, 
kActionQTVRSetTiltAngle). Also, I’ve wired the buttons to 
respond to mouse-over events, not mouse-click events. 

Targeting two external movies with the same sprite action is 
extremely simple. Let's suppose that the summer and winter 
panoramas have the target names “Summer* and “Winter”, 
respectively. Then we can w ire the Tan Left” sprite using the 
code shown in Listing 12, 

Listing 12: Wiring a sprite to control two external movies 

Q ITars AddV r R< !oin r<D I It.: rlkjr rtin Sjim pk? > V] cUj ;i 

^define kTargetl “Sumner 11 

jfdeflne kTarget2 "Winter'* 

SrringPtr myMovieNames[2]; 


myMovieNames[0] = QTUtile„CQnvertCToPascalString(kTargetl): 
ijiyMovieNames [I] - QTUtils_ConvertCToPascalString(kTarget2); 

for (myCount = 0 : myCount <= 1; tnyCount^H) { 

SpriteUtils_SetSpriteData(myPanLeftButton, ^tnyLocation, 

fcisVisible, kroyLayer, &jnylndex, NULL. NULL, NULL); 

WiredUtils_AddEprite5etImageIndexActi&n[myPanLeftButton l 

kParentAtonlsContainer, kQTEventMouseEnter. 0, NULL, 

Q f 0. NULL. kPanleftDowiiIndex, NULL): 

WiredUtils_AddSpriteS-et ImagelndexAc tian Cray PatiLeftButton, 

kParentAtomlsContainer, kQTEventMouaeExit, 0, NULL. 

0, 0. NULL, kFanLeftUpIndex, NULL); 

WiredUtiIs^AddSpriteTrackSetVarlableAction(nyPanLeftButton, 
kParentAtomlsContainer, kQTEventMouseEnter, 
kHouae0verP anLeftVariafeleiD* 1, 0, NULL. 0); 

WiredUtils_AddSpriteTrackSetVariableActionCmyPanLeftButton, 
kParentAtomlsContainer, kQTEventMouseExit, 
kMauseOverPanLeftVariahlelD, 0, 0, NULL, 0): 

QTTar g^ddlftleEventVar Test Act Ion CmyPanLaftButton, 

kPa rentAtomlsContainer, kNouseOve rPanLeftVariablelD* 
t , kActionQTWSetTiltAngle, &jnyActionAtom); 

WiredUtils_AddAc tionPa ranteterAtom[myPanLeftButton. 

ntyActionAtora, kFirstFararo, sizeof (myDeltaAngle), 
yDe11aAn gle. NULL); 

WiredUtila_AddAc tiotiParatnet erOptions (my PanLef tButton. T 

myActionAtora, 1, kActionFlagActionlsDelta* 0, NULL, 

0. NULL); 

WiredUtils_AddMovieNameActionTargetAtoin {myPanLeftButton, 
myActionAtom, tnyMovieNames1myCount]. NULL); 

1 

The key element here is the call to 
Wired Utils^AddMovieNameActionTargetAtom, which adds the 
appropriate movie name target atom to the action atom, You’ll 
also notice that we call the application function 
QTTarg_AddldleEventVarTestAction 1 which installs an idle event 
action that checks to see whether the specified variable (in tills 
case, the one with ID kMouseOverPanLeftVariablelD) has the 
value specified in die fourth parameter; whenever it does, the 
specified action is executed. (See GTActionTargets.c for die 
complete listing of QTTarg J\dd Idle Event VarTestAction.) 

Retrieving a Movie’s Own Target Name and ID 

QuickTime 5 recently introduced two new operands related 
to movie target names and IDs, kOperandMovieName and 
kOperandMovielD. Wired actions can use these operands to 
determine the name and ID of a target movie. Once again, the 
movie controller handling these operands needs some help from 
our application to get the desired information, (In a sense, this 
is the flip-side of the task we considered earlier. In diat case, a 
movie controller had a movie’s target name or ID and we 
needed to rind the movie and movie controller associated with 
that name or ID. In the present case, the movie controller is 
known and we need to find the movie target name or ID 
associated with that movie controller.) 

When a movie controller encounters the 
kOperandMovieName or kOperandMovielD operand and hence 
needs to get a movie’s name or ID, it sends the 
mcActionGetMovieName or mcActionGetMovieiD movie controller 
acdon to the movie controller associated with that movie. Our 
application should respond to these actions by returning the 
movie target name or ID, Let’s consider first the 
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me ActionGetMo v i e ID action. When our movie controller action 
filter function receives this action, the theParams parameter is a 
pointer to a long integer. If the movie indeed has a movie target 
ID, we should return that ID in that long integer and also return 
true as the return value of our filter function. Otherwise, we 
should return false as the return value of our filter function. 
Listing 13 shows the lines of code in our movie controller action 
filter function that handle the mcActionGetMovietD action. 


Listing 13: Getting a movie’s target ID 

QTApp JVlCAction FilterProc 


case me Ac ti□nGelMov1eID: 

myMovie = (**ntyWindovObject) .fMovie; 
if {myMovie I® NULL) t 
long my ID: 

Boolean myMovieHaslD ■ false; 

// get the target name of the current movie 

myID " QTUtils_GetMovieTargetID(myMovie, &myKovieHasID); 
if (itiyMovieHasID) ( 

# (long *)theParams = myID; 
isHandled = true; 


1 

break: 


As you can see, this code uses the QTUtils_GetMovieTargetlD 
function to get the target ID of the current movie, if the movie 
has no target ID, we don't put any value into theParams and we 
allow the filter function to return the default value of false. 

When our movie controller action filter function receives 
the mcActlonGetMovleName action, the theParams parameter is a 
handle to a Pascal string. In this case, we need to determine the 
target name of the movie and copy it into that Pascal string. 
Listing 14 shows the code that handles this. 

Listing 14: Getting a movie’s target ID _ 

QTApp_ MOctiGfiFdterPfoc 


case mcAc tionGetMovieName; 

myMovie = (**inyWindovrObject) .fMovie; 
if {myMovie != HULL) [ 
char *myName = NULL: 

Handle myNameHandle « (Handle)theParams; 

// get the target name of the current movie 

myName ® QTUtils„GetMovieTargetNarae(myMovie); 

if ((tnyName != MULL) || (ntyNameHandle != NULL)) [ 

// reset the size of the handle passed to us to hold the movie target name 
SetKandleSizetmyNanieHandle. etrlen(myName + 1)); 
if (MemError() =■ noErr) I 

// copy the movie target name into the resized handle 
BlockMove(myName, *TuyNameHarLdle + 1, strlen(myNaiDe)); 
*tny Name Handle [0] = strlen(myName) ; 
isHandled = true; 

J 

1 

free{myName]; 

) 


break; 


1 Iere, we use our function QTUtils_GetMovieTargetName (defined 
in Listing 8) to get the movie target name. Notice tliat we need 
to resize the handle passed to us in order to ensure that it's large 
enough to hold the name we pass back. 

Operand Targets 

Recall that wired action operands typically retrieve 
properties of some element of a movie, such as a track’s height, 
a movie’s duration, a sprite’s image index, a sprite track 
variable's value, and so forth. The element of the movie whose 
property' is to be retrieved is the operand target As with actions, 
each operand that has a target also has a default target. But also 
as with actions, it’s possible to specify some other target for an 
operand by inserting a target atom into the operand atom. So, 
we can say things like: get me the image index of the sprite 
named "Old QuickTime icon” in the second sprite track of the 
movie whose target ID is IT In this section, we’re going to play 
a little with operand targets; along the way, well discover that 
they can be a bit trickier than they seem. 

Let’s begin by targeting a wired action (and not an operand ) 
at an object in an external movie. Consider once again the 
moving icon movie that we constructed in W A Goofy Movie” (in 
MacTecb , March 2001), shown in Figure 5 Let’s assume that this 
movie contains the plug’ user data necessary to set its target 
name to ’Icon Movie”. 
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Figure 5: The moving icon movie 

Now suppose that we've created some other movie with a 
sprite track, maybe the one shown earlier in Figure 3- (Let's also 
assume that the target name of this movie is ‘‘Button Movie".) We 
want to rewire the sprite button so that clicking on the button 
changes the image index of the sprite in die moving icon movie. 
When we first open die moving icon movie, the image index of 
the icon sprite is 1. !so let's reset that index to 2. 

With the machinery we have at hand, this is pretty 
straightforward: we just insert a kActionSp rite Set I mage index 
acdon atom into the button sprite atom, together with a 
parameter atom whose atom data is the constant 2. We also add 
to die action atom a target atom that picks out the sprite with ID 
1 in the first sprite track in the movie w r hose target name is “Icon 
Movie”. Listing 15 shows our revised wiring. 

Listing 15;_Setting the image index of an external sprite 


#define kTargetName "Icon Movie 1 ’ 

Wiredntils_AddSpriteSetImflgelndexAction (myTextButton, 

kParentAt□misContainer, kQTEventMouseClick, 0* NULL, 

0. 0. NULL. kTextDovnindex. NULL): 

WIredUtils_Add5priteSetImageIndexAction(myTextButton. 

kParentAtomlsContainer* kQTEveritMouseClickEndU 0, 

NULL. 

0*0, NULL, kTextUpIndex* NULL): 

WIredUtil£_AddQTEventAndActionAtoras(myTextButton. 
kParentAto nils Container * 
kQTEventMouseClickEndTriggerButton, 
kActionSpriteSetlmagelndex, fnnyActionAtom); 

myIndex = EcdlanS16_NtoB(2): 

WiredUtils_AddActionParanietexAtom(myTextButton, rayActionAtom * 
kFirstParam, sizeof(myIndex), imylndex, NULL) 

WiredUti1 s_AddTrackAndSp riteTar getAtoms{myTextButton, 
myActi onAt out. kTaxgetTrackType, [void *) 
SpriteMediaType. 1, kTargetSpritelD, (void *)1); 

myStrlng D QTUtils_ConvertCToPascaIString(kTargetName); 

WiredUtilE_AddMovieTargetAtoin[myTextButton* myActionAtom. 
kTargetMovleName. (void *)jnyString): 

freefmyString); 


So far, so good. Now let's see what happens if we try' to specify 
the new image index using an expression that contains an operand. 
For instance, let s try 7 to read the image index from a sprite track 
variable. First, of course, we need to initialize the variable; we can 
do this with a frame-loaded event action, like so: 

float myVariableValue - 2: 

QTAtomID myVarlablelD = 1234; 


WiredUtils_AddSp -riteTrackSetVaxiableAction(mySample, 
kParentAtomlsContainer, kQTEventFraraeLoaded. 
myVarlablelD, myVariableValue, 0, NULL, 0); 

Now we need to revise the sprite button wiring to use that 
variable instead of the hard-coded constant 2, Listing 16 shows 
our first try. 

Listing l6: Setting the image index of an external sprite 
using a variable 

WiredUtil s_AddQTEventAndActionAtoms{myTextButton. 
kFarenlAtomlsContainer, 
kQTEventMous eC1ickEndTrig ge rBut t on * 
kActionSpriteSetlmagelndex, &myActionAtom): 

QTInsertChild(myTextButton * myActionAtom * kActionParameter * 

0* kFirstParatn, 0, NULL, &myParamAtorn); 

QTInsertChiId(myTextButton. myParamAtoni, 

kExpressionCQntaiuetAtoinType, 1. 1, 0. NULL. 
fcmyExpressionAtora); 

QTInse11Chi1d(myTextButton, myExpress!onAtom. 

kOperandAtomType, 0* 1. 0, NULL, imyOperandAtom) : 

QTInsertChild(myTextButton, tnyOperandAtom. 

kOperandSpriteTraekVariable. 1. 1. 0. NULL. 
&myGperandTypeAtom); 

myVariableID = EndlanU32_NtoB(myVariableID); 

QTInsertChild(myTextButton. myOperandTypeAtom. 

kActionParameter, 1, 1, sizeof(myVariabletD)* 
kmyVariablelD. NULL): 

WiredUti1s_Ad dT ra c kAnd Sprit eTa r ge tAt oms(myTextBut t on * 
myActionAtom. kTargetTrackType, (void *) 

SpriteMediaType. 1. kTargetSpritelD, (void *)1); 

myString = QTUtUs_ConvertCToPascalStringfkTargetName}; 

WiiedUtils_AddNovieTargetAtom(myTextButton, myActionAtom. 

kTargetMovieName, (void *)myStritig); 

free(myString): 

There's only one problem: ihis doesn’t work. The reason is 
that the sprite button movie’s movie controller sees that the 
kActionSp rite Set Image Index action is targeted at the icon movie, 
so it sends die entire action atom over to the movie controller of 
the icon movie for handling. When the movie controller of the 
icon movie tries to get the value of die sprite track variable with 
ID 1234, it discovers that there is no such variable defined yet. 
In that case, it sets die icon’s image to 0 (which is the default 
value of all uninitialized sprite track variables). Instead of 
changing the image index to 2, the movie controller changes it 
to 0 and the icon sprite promptly disappears. Oops. 

This is where operand targets come into play. What we 
need to do is attach a target atom to the 
kOperandSpriteTrackVariabte operand that picks out the sprite 
track that contains the sprite button (that is, the track in w hich 
we set the value of the variable with ID 1234). Listing 17 shows 
the essential part of our re-revised wiring. 

Listing 17: Adding a target to an operand atom 

^define kButtonName "Button Movie" 

// explicitly target the sprite tnck and movie for the operand 

myStriug = QTUtilsJ^onvertCToPascalStringCkButtonName); 
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rayOperandTypeAtQK]. kTargetTrackType. 

(void *)SpriteMediaType. 1, kTargetSpritelD. 

{void *)1): 

WiredUti1s_Ad dMo - vieTa r ge tAtom(myTe xtButt o n * 
myOperandTypeAtom, kTargetMavieName, 

(void ‘)myString); 
free(myString): 

This works fine, but it seems to violate the *no self- 
targeting* rule adopted by QuickTime Player. After all, the sprite 
track in the movie "Button Movie” explicitly targets the movie 
"Button Movie”, So we might expect this wiring to work in 
QTActionTargets but not in QuickTime Player, right? Nope, it 
works fine in both applications. Remember that when the movie 
controller of the button movie detects an action targeted at an 
external movie, it sends the action atom off to the movie 
controller of that movie. The target atom in the operand atom is 
evaluated and resolved only by the movie controller of the icon 
movie, in which case it's not a self-reference at all; rather, it T s 
now targeting the sprite button movie. So both applications, 
QTActionTargets and QuickTime Player, are able to find the 
track containing the relevant variable and retrieve its value. 
There are a couple of important lessons to take away from 
all this. First and foremost, action targets and operand targets are 
resolved only at run time. As a result, the target of an action or 
operand can change if some of the properties of the movie 
change, (For instance, the sprite with a certain ID might differ 
from the sprite with that same ID, if the movie time is changed 
so that a new key frame of the sprite track is loaded,} Also, a 


target atom contained in an action or operand atom is always 
interpreted relative to any target atoms contained in the parents 
of that action or operand atom. If a parent action or operand 
atom changes its target to some other sprite, track, or movie, 
then all its children will inherit that change. The only way to be 
absolutely sure that we know what an action or operand is 
targeting is to build the atom hierarchy very carefully or to give 
a full, explicit target, 

Movie-in-Mgvie Communication 

Let's finish up with something perhaps a little less dizzying. 
In an earlier article ("The Atomic Cafe” in MacTech , September 
2000), we learned how use the movie media handler to embed 
one movie (called the child movie) inside of another movie (the 
parent movie). The main advantage of using this movie-in-movie 
capability is that the parent and child movies can have 
independent playback characteristics, This means that the 
looping state or the playback rate of Lhe parent movie can differ 
from the looping state or the playback rate of the child movie. 

We embed one movie inside of another movie by creating 
a movie track whose samples are atom containers that contain 
atoms that pick out the child movies and specify their playback 
characteristics, (See the earlier article for more complete details 
on creating movie tracks,) In this section, we'll see how to work 
with embedded movies and wired actions. Things work pretty 
much as you'd expect, but there are a couple of new' capabilities 
that deserve attention. 
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Specifying Movie-in-Movie Targets 

We can send wired actions from a parent movie to a child 
movie and from a child movie to a parent movie. If we want to 
send a wired action from a child to a parent, we can target the 
parent using one of these two target types: 

enum I 

kTargetRootHovie “ FOUR_CHAK_CODE (' n»oro') * 

kTargetParentMovie = F0UR_CHAR_C0DE ['tnopa'} 


A child's parent movie, of course, is the movie that 
contains the movie track that references the child movie. 
The root movie is the movie at the top of the parent/child 
hierarchy. When a parent movie contains a child movie 
that does not itself contain any movie tracks, then the 
parent and the root are the same. But a child movie can 
easily contain its own children (it is after all a movie, so it 
can contain movie tracks), and this containment hierarchy 
can go indefinitely deep. So ids useful to have a way to 
target Lite movie at the root of the hierarchy, and that's 
what klargetRootMovie gives us. 

A child movie is a movie chads picked out by a data 
reference contained in a sample in a movie track. So it 
has a sort of “dual nationality”: we can target is as if iL 
were a movie or as if it were a track. To target it as a 
movie, we can target its movie ID or its movie name. And 
to target it as a track, w F e can target its track ID, its track 
name, or its track index. There are therefore five ways for 
a parent movie (or some element of a parent movie) to 
target a child movie. The file Movies.h defines these five 
constants for specifying a child movie target type: 


enum I 

kT&r get ChildHovie Tra c kNam e 
kTa rge tChildMo vieTr a ckID 
kTargetChildMovieTracklndex 
kTa r get Chi1dMavieMo vieName 
kTa rgetChildMovieMovielD 

1 ; 


= FOUft_CHAR_COD£f 1 motn 1 ), 
= FOUR_CHAR_CODE{"moti'), 
= FOUR_CHAR_CODE{’motx'), 
= F0UR_CHAR_C0DE {' mourn h ), 
= F0UfLCHAR_C0DE{ K momi 1 ) 


These are all easy enough to figure out. except perhaps 
for kTargetChildMovieTracklndex. An atom of this type 
targets a track with a specific index in a movie, which had 
better be a movie track (that is, a track of type 
MovieMediaType). As far as I know, we cannot directly 
target a child movie by its index among just the movie 
tracks. 


Using Movie-Loaded Events 

QuickTime 4.1 T which introduced the movie-in-movie 
capability and the five new target types, also introduced 
a new kind of event for triggering wired actions, the 
movie-loaded event. A movie-loaded event (of type 
kQTEventMovteLoaded) is issued whenever a child movie 
is loaded into a parent movie. We can construct wired 
event handlers to look for this evenL and execute wired 
actions when it is received. The movie-loaded evenL is 
particularly useful for configuring the child movie based 


on some of the current properties of its parent, or 
conversely for configuring the parent based on some of 
the properties of the child. 

Event atoms of type kQTEventMovieLoaded can be put 
into the parent movie or into a child movie, in a parent 
movie, a movie-loaded event atom is placed into the atom 
container that comprises a sample in a movie track, as a 
sibling of the kMovieMediaDataReferenee atom (which 
picks out the child movie). In a child movie, a movie- 
loaded event atom is inserted into the movie property 
atom. A movie property atom is an atom container that 
contains information about the movie's properties, in just 
the same way that a track's media property atom (which 
we encountered in “A Goofy Movie", cited earlier) 
contains information about the properties of the track and 
its media. We can insert a movie-loaded event and its 
accompanying actions into a movie property atom by 
calling the GetMoviePropertyAtom function, inserting the 
atom, and then calling SetMoviePropertyAtom. 

If a parent movie and a child movie both contain 
movie-loaded event atoms, then the actions in the child 
movie's event atom are executed first, followed by those in 
the parent movie’s event atom. That is to say, the parent 
gets the final word here. (Who says movie don't accurately 
portray reality?) For instance, if both the child movie and 
the parent movie set the value of some sprite track variable, 
then the parent’s assignment overrules the child's. 

Conclusion 

In this article, we've touched on just about eveiy 
possible way of targeting a wired action or operand at 
some dement of a movie, no matter where that element 
resides. The target could be in the same track as the event 
atom that Lriggers the action or in another track; it could 
also be in an external movie or in a child or parent movie. 
In all these cases, we link the action or operand to the 
target by inserting an atom of type kActionTarget into the 
action or operand atom. The movie controller is 
responsible for resolving these target atoms at run time and 
dispatching the actions or operands to the appropriate 
target. We've also seen that the movie controller sometimes 
needs our help in finding targets; if an action or operand 
targets an external movie, our application needs to step in 
and find the specified target movie. 

In the next article, we’ll take one final look at wired 
actions, ar least for the moment. Well see that wired 
action atoms can be associated with objects other than 
sprites, and we’ll investigate some of the newer event 
types and actions. 


Credits 

Thanks are due to Steve Dawson for permission to use 
his excellent panoramas of die Danner Lake area. 
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■ Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 


* Fully supported; it's easier, faster, and more productive than ResEdit 

* Safer memory-based, not disk-file-based, design and operation 

* All file information and common commands in one easy-to-use window 

* Compares resource files, and even edits your data forks as well 

* Visible, accumulating, editable scrap 

* Searches and opens/marks/selects resources by text content 

* Makes global resource ID or type changes easily and safely 

* Builds resource files from simple Rezdike scripts 

* Most editors DeRez directly to the clipboard 

* All graphic editors support screen-copying or partial screen-copying 

* Hot-linking Value Converter for editing 32 bits in a dozen formats 

* Its own 32-bit List Mgr can open and edit very large data structures 

* Templates can pre- and post-process any arbitrary data structure 

* Includes nearly 200 templates for common system resources 

* TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

* Full integrated support for editing color dialogs and menus 

* Try out balloons, detb’s, lists and popups, even create C source code 

* Integrated single-window Hex/Code Editor, with patching, searching 

* Editors for cursors, versions, pictures, bundles, and lots more 

* Relied on by thousands of Macintosh developers around the world 


To order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website... 

www.mathemaesthetics.com 
















PROGRAMMER'S 

CHALLENGE 


by Bob Boomtra, Westford , MA 


Dots 

You have probably played the game Dots before; 
although perhaps not in quite some time. My memory of 
the game dates back to childhood, when we played it in 
the car while on some long trip. Greg Sadefsky suggested 
that Dots might make an interesting Challenge, and he 
wins two Challenge points for that suggestion. 

The game starts with a piece of paper with a 
rectangular grid of NxN dots. The game proceeds with 
two players alternating turns connecting adjacent dots 
with a line, Two dots are adjacent if they are in the same 
row and in adjacent columns, or in the same column and 
in adjacent rows. The object of the game is to take 
possession of more squares than does your opponent. 
Each time a player connects dots that form the fourth 
edge of a square, the player takes possession of that 
square. A line can complete zero, one. or two squares. 
When a player completes one or more squares, s/he is 
entitled to make another move, and to continue making 
additional moves as long as a square is completed with 
each move. The game continues until every square has 
been formed. 

The prototype for the code you should write is; 

typedef struct Dot t 

short row ; F row number of dot, 0 . .txKudSizc-l V 

short col; F column number of dota.boattKtoscq V 

I Dot i 

typedef struct DotLine ! 

Dot dotl; F first dot of a line 7 
Dot dot 2; F second dot of a line 7 

F legal lines ;im formed by dots in the same row* in adjacent columns, or in the same 
column in adjacent rows 7 
I DotLine; 

void InitDDtsf 

short board Size, F number of dots per row/col in Ixxtrd 7 
Boolean playFi rst, F true if you play first, false of opponent plays first 7 
WindowPt r dotWindow F color window where wju should draw game results 7 

); 

void OpponentHove( 

const DotLine opponentLine F Hrje formed by your opponent on 

previous move 7 


short F number of lines generated 7 Play Dot# 

DotLine your Lines [] F return the lines you form here 7 

)/S 

void T e r mD o t s {v o i d); /’return any st orage you allocated 7 

Play begins with a call to your InitDots routine, where 
you are given the size of the game board (boardSize), an 
indicator of who plays first (playFirst), and a pointer to a 


CWindow (passed as a WindowPtr because that's what most 
toolbox routines expect). In that window, you will be 
required to display the progress of the game as it proceeds. 

When it is your turn to move, your PlayDots routine 
will be called. Your code should select the most 
advantageous move and return it in yourLines[0]. If that 
move forms a square, you can select an additional move, 
store it in yourLines[1], and continue as long as squares are 
formed. PlayDots should return the number of moves you 
made during your turn. 

After your opponent has played, your OpponentMove 
routine will be called one or more times, once for each 
move made by your opponent. The move will be provided 
in the opponentLfne parameter, for use in display and in 
updating your data structures. 

After each of your moves, and after notification of 
each opponent move, you should display the move and 
the updated game state in the dot Window. The window 
should also display the number of squares completed by 
each player. The details of the display are left to you, as 
long as the display is correct. 

When all of the squares have been formed, your 
TermDofcs routine will be called. You should deallocate 
any dynamically allocated memory and perform any other 
cleanup required. 

The winner will be determined by a round-robin or 
other fair tournament played with multiple board sizes. 
Scoring is based on minimizing your point total, calculated 
as the number of squares Lhai your opponent occupies, 
plus a penalty of 1% for each millisecond your solution 
takes to execute. 

The Challenge prize will be divided between the 
overall winner and the best scoring entry from a 
contestant that has not won the Challenge recently. 

This will be a native PowerPC Challenge, using the 
Code Warrior Pro 6 environment. Solutions may be coded 
in C, C++, or Pascal. 

Three Months Ago Winner 

Congratulations to Claes Wihlborg for wanning the 
March DragSort Challenge. The object of this Challenge 
was to sort a list by dragging items from one position to 
another, minimizing the cumulative distance that the drag 
cursor traveled while moving to pick up an item and while 
dragging it to its new position. Four of the five entries I 
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Awaken the Guru Within You 

The pressure is on. You've got deadlines to hit, high expectations 
to meet, and complex technology issues to resol ve. And just 
when the challenges you face on the Web are intensifying, 
along comes mobile technology. 

Now you and your team must create Internet and mobile 
solutions that raise your organization to a whole new level of 
efficiency and productivity. Clearly the path to technological 
nirvana has never been easy. WEB2001 and Internet+Mobile 
can show you the way 


Successful Web teams depend on WEB2001 to help them 
anticipate, evaluate, and implement the latest Web strategy 
user experience, and technology. This year, the newly launched 
Internet+Mobile conference will also prepare you to leverage 
mobile technology to extend your Internet enterprise. 

Gain essential knowledge from the masters of the Web and the 
pioneers in mobile. Be inspired by fellow gurus from the far 
reaches of the earth and right next door. And meet the technology 
providers that will transform your business strategies Into reality. 
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received sorted my test cases correctly, and three of the 
four used the same basic algorithm. Claes 5 entry, however, 
did so much more efficiently than the others, earning him 
the Challenge win. 

The winning solution moves down the list and picks 
up Lhe first out-of-order item, dragging it in the same 
direction and dropping it before the next in-order item. It 
then continues scanning the list in the same direction, 
picking up the next out-of-order item and dropping it 
were it belongs. When it reaches the end of the list, it 
reverses direction and does the same thing moving 
backward. It continues to move up and down the list until 
all of the items are in the correct order. A straightforward 
and efficient solution, 

1 evaluated the entries using six test cases using lists 
ranging up to 6500 elements. Since the problem was based 
on a hypothetical Usenet application, most of the test cases 
were based on lists that were ordered correctly except for 
some relatively small percentage of the list items. 

As the best-placing entry from someone who has not 
won a Challenge in the past two years, Randy Boring 
wins a share of this month's Challenge prize. You don't 
need to defeat the Challenge points leaders to claim a pari 
of the prize, so enter the Challenge and win Developer 
Depot credits! 

The table below lists, for each of the solutions 
submitted, the number of penalty points earned by each 
entry, the total time in milliseconds, and the number of 
select and drag position moves used to sort the test cases. 
It also lists the code size, data size, and programming 
language used for each entry. As usual, the number in 
parentheses after the entrant’s name is the total number of 
Challenge points earned in ail Challenges prior to this one. 

Name Points Time 

(msecs) Moves Code 

Size Data Lang 
Size 


Claes Wihlbwg (29)29026776 

180 

29026284 

704 

8 

C++ 

Ernst Munter (721)29026987 

706 

29026284 

2380 

80 

C++ 

Randy Boring (135)29027737 

I486 

29026284 

2212 

145 

C++ 

Marco Aiello 84384025 

4600 

84379428 

1416 

28 

C++ 

R O. Incorrect 

N/A 


43432 

6120 

C++ 



Top Contestants 

Listed here are the Top Contestants for the 
Programmer’s Challenge, including everyone who has 
accumulated 20 or more points during the past two years. 
The numbers below include points awarded over the 24 
most recent contests, including points earned by this 


month’s 

months, 

entrants, the number of wans over the past 24 
and the total number of career Challenge points. 

Rank 

Name 

Points 

Wins Total Points 
(24 mo) (24 mo) 

1 . 

Munter, Ernst 

294 

11 

731 

2. 

Rieken, Willeke 

87 

3 

134 

3. 

Saxton, Tom 

76 

2 

185 

4, 

Maurer, Sebastian 

68 

2 

108 

5. 

Taylor, Jonathan 

56 

2 

56 

6. 

Shearer, Rob 

55 

1 

62 

7. 

Wihlborg, Claes 

49 

2 

49 


... and the Top Contestants Looking for a Recent Win 

In order to give some recognition to other 
participants in the Challenge, we also list the high scores 
for contestants who have accumulated points without 
taking first place in a Challenge during the past tw r o years. 
Listed here are all of those contestants who have 
accumulated 6 or more points during the past two years. 

Rank 

Name 

Points 
(24 mo) 

Total Points 

8, 

Boring, Randy 

39 

142 

9. 

Jones, Dennis 

12 

22 

10 , 

Sadetsky, Gregory 

12 

14 

11 , 

Downs, Andrew' 

12 

12 

12, 

Day, Mark 

10 

30 

13. 

Duga, Brady 

10 

10 

14. 

Fazekas, Miklos 

10 

10 

15. 

Flowers, Sue 

10 

to 

16. 

Strout, Joe 

10 

10 

17. 

Nlcolle, Ludovic 

7 

55 

18. 

Hala, Ladislav 

7 

7 

19. 

Miller, Mike 

7 

7 

20. 

Sc hots man, Jan 

7 

7 

21. 

Widyatama, Yudin 

7 

7 

22. 

Heithcock, JG 

6 

43 


There are three ways to earn points: (1) scoring in the 
top 5 of any Challenge, (2) being the first person to find 
a bug in a published winning solution or, (3) being the 
first person to suggest a Challenge that I use. The points 


you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5 tli place 

2 points 

finding bug 

2 points 


suggesting Challenge 2 points 


58 
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DAVE? 


It’s totally cool! 


THURSBY SOFTWARE has the 
perfect file share solution to 
meet your needs. 



The ideal solution for the small 
office where Macs & PCs need 
to share files. 



The fast, easy way to share 
files and printers between 
PCs and Macintosh systems. 



Haw cool would it be for your Macs and PCs to become best friends? To share text 
and graphics files and postscript printers across a network with no barriers. Get 
DAVE, the “totally cool" file share solution from Thursby Software. DAVE installs 
on your Mac. It’s fast, secure and simple to use... perfect for sharing with Windows 
95/98/Me/NT/2000 and soon, for Mac OS X. 

Download a FREE EVALUATION today. 



T 


THURSBY 

Software 


file 6lare folk*?* 

www. thu rsby,com 

© 2Ml TTiuirfcy Software System*, Inc* 


Achieve true NFS connectivity 
between your Mac and 
UNIX systems. 




Windows users can access 
files on any Mac workstation 
or AppleShare server. 




















Here is Claes' winning DragSort solution: 


DragSorLcp 

Copyright © 2001 

Claes Wihlborg 

r 

The program takes a very simple approach and implements 
bubbJesort with alternating sort directions, 

V 

^Include "DragSort.h" 

//---*-—-—- 

DragSort 

long /* numMoves 7 DragSort ( 

long itensToSort [] 4 f* array of items to be sorted */ 

long mnnItemsToSort, /* number of itemsToSort 7 

long startPosition, Z 1 item initially selected 7 

Hove aortMoves [] /* store Moves that sort the army here 7 


Move *nextMove = sortHoves; 
long temp t temp2: 

long *p. *oldp. *pMin. *pMax. *newMin, ‘newMax: 
pMin = itemsToSort: 

pMax = ItemsToSort + numltemsToSott 1; 

// If strartpos <> 0, sweep down 

p = ItenssToSort + startPoaitioo; 

While{ p > pMin ) 

t 

oldp ” p“i 

ift (temp = *oldp) < ‘p ) 

I 


nextMove->selectPosition = oldp - itemsToSort; 
do 

l 

•oldp = *p; 
oldp - p~; 

J 

whilst tp pHin) && (temp < *p ) ); 
nextMove++->dragToPosition = oldp - itemsToSort; 
‘oldp = temp: 

1 

1 

// list iteration: sweep once up and once down, 

// this iteration puts at least the smallest and the biggest items in place. 

newMax = 0; 
newMin = 0; 

p = pMin; 

while ( p < pMax ) //sweep up 
I 

oldp ” p++; 

if£ (temp = *oldp) > (temp2 = *p) ) 

I 

nextMove>eelectPosition = oldp - itemsToSort: 

do 

l 

•oldp = temp2; 
oldp = p++; 

1 

vhile( (p <= pMax) && (temp > (temp2 = “p)) )i 
nextMove++->dragToPosition = oldp - itemsToSort; 
*oldp = temp; 
newMax = oldp; 

I 

I 

if( !newMax ) return nextMove - sortMoves; 

// no more items in wrong order 

pMax = newMax * 1: 
p “ pHax: 

while ( p > pMin ) //sweep down 



SUPERIOR 


Xcaret Pro Expansion Bay CDRW Drives 



Bootable! * Hot Swappable * Fast Backup or Fite 
Toast™ 4 Software * Protective MCE Carrying Case 
Available for PowerBook G3 98 (Walt Street) or 
PowerBook G3 99 & 2006 (Lombard & Pismo) 

iTunes and Disc Burner Compatible! 


Internal Hard Drive Upgrades for Power Books 

* TIte BEST Internal Hard Drive Upgrade Kits for your PowerBook! 

* Package includes bard drives from the same manufacturers that 
shipped in the PowerBook from the factory bundled with 
everything you need for a successful installation 

* High-Speed WGB , 20GB, and 36GB Capacities 

DataShuttle Xtreme Portable Hard Drive 

* The Most VERSATILE Portable Hard Drives Anywhere 

* FireWire Hard Drives with Flexible USB and PC Card Options 

* High-Speed 10GB, 20GB, and 30GB Capacities 

* Also available, the Do-it-Yourseif DataShuttle Xtrem e Kit - 
Convert Your old Internal Drive into a Portable External Drive! 




POWERBOOK 

__ a Great V 

Xcaret Pro Expansion Bay Hard Drives 

__ leaim; 

■ Ultra FastI * Hot Swappable • Bootable 

■ Compact * Protective MCE Carrying Case 

■ High-Speed WGB, 20GB, and 30GB Capacities 
•Also available, me Xcaret Pro Expansion Bay Kit - 

Convert Your old Drive into an Expansion Bay Drive! 

•Available for PowerBook G3 98 or PowerBook G3 99 & 2000 



USB FlexLight 


"lllu m in a te Yo ur Workspace " 



* Conveniently fights up your keyboard and surrounding 
paperwork , * Twists and Bends so You can Direct the 
Light Where You Want it * Powered by the USB Port 

• Comes with Both a dear and a Red Diffuser - You Choose the 
Type of Light to Suit Your Situation * Very Low Power Draw 



Hoc Components Engineered a 


For more inTo; 

www.mcetech.com 

800.500.0622 

949.458.0880 

Contact us for a dealer near you 















sbObjects Adaptors 
ALbasic Plugin 
jlti-Threaded Server 
iw Level Locking 
1 0 MB Searchab le Blabs 
itc base Replication 
itabase Ma nogement Tools 
aphical Schema Design Tools 
mote Administration 


tactions each day. 
d Base performance has 


hiArrivah.tom 


over 2 Million Transactions per day, FlightArrivals.com flies with Open Base SQL 

Take OpenBase SQL for a Test Flight Today! ^ 

Get Your FREE Developer's License at www.openbase.com OpenBase 


oldp = p—; 
if( (temp 


oldp} < [temp2 “ *p) ) 

oldp - itemsToSort: 


nextMove->selectFosition 

do 


//simpler condition as biggest element in correct place 

nextMove++->dragToPosition = oldp - 
itemsToSort; 

*qldp “ temp; 
newMax = oldp: 

1 

I 


I 

*oldp - temps: 
oldp ” p-; 

) 

whilst (p >= pMin) && (temp < (temp2 = ’p)) ); 
nextMove++->dragToFosition = oldp - itemsToSort; 
*oldp - temp; 
newMin = oldp: 


if[ InewMin ) return nextMove - sortMoves; 

// no more items in wrong order 
pMin = newMin + 1: 

do //main loop: sweep once up and once down for every iteration 

( 

newMax - 0; 
newMin = 0; 

p * pMin: 

while ( p < pMax ) //sweep up 
I 

oldp = p++; 


if( lnewMax ) break: //no more items in wrong order 

pMax “ newMax - 1; 
p • pMax: 

while{ p > pMin ) //sweep down 
[ 

oldp “ p-; 

if C (temp = *oldp) < [temp2 = *p) ) 

I 

nextMove->solectFosition “ o lip - itemsToSort: 

do 

I 

“oldp = temp2; 
oldp = p—; 

) 

while£ temp < (tempi *= *p) ); 

//simpler condition as smallest element in correct place 
nextMave-H->dragTqPosition = oldp - itemsToSort: 
“oldp = temp: 
newMin = oldp: 

I 

\ 


if( (temp = *oldp) > (temp2 “ *p) ) 

[ 

nextMove->selectPosition = oldp - itemsToSort; 
do 


“oldp = temp2; 
oldp = p*h+; 

J 

while( temp > (temp2 = *p) ); 


pMin 


newMin + 1; 


J 

while( newMin ); 

return nextMove - sortMoves: 
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Beyond QuickDraw: Quartz 

A Brief Introduction to Mac 0$ X’s New Imaging Model 


or nearly two decades, Macintosh graphics have revolved 
around QuickDraw, QuickDraw was revolutionary, offering a 
unified imaging model that could be used for application 
drawing, printing, and providing a platform-wide graphics format. 
Unfortunately, today's applications frequently require graphic fun¬ 
ctionality that exceeds QuickDraw's reach. Developers frequently 
have to work around issues such as the lack of spline-based curves 
and text rotations. With the introduction of Mac OS X, a revolution¬ 
ary new imaging model—Quarts—is ready to meet the needs of cur¬ 
rent and future applications. 

This article is a brief introduction to Quartz and will focus on 

its architecture and functionality. 
Where appropriate, this article 
will also call out various technical 
resources that will help you take 
advantage of what Quartz has to 
offer. 

What is Quartz? 

Quartz is a set of powerful 
graphics services that form the 
graphics component of Mac 
OS X's application services 
layer. In this role, Quartz pro¬ 
vides the rest of the system 
with a powerful 2-D render¬ 
ing engine that supports advanced 
vector graphics {complete with anti-aliasing and transparency 
support.) Quartz also implements the windowing system for Mac 
OS X and provides low-level services such as system-wide evenL 
handling. Quartz plays a key role in Mac OS X’s printing architec¬ 
ture as well and provides rasterization and conversion services for 
print jobs. 

The Quartz Architecture 

As noted in Inside Mac 05 X: System Overview, Quartz is actually 
composed of two separate parts that perform different functions: 
Quartz Compositor and Quartz 2D, 




Quartz Compositor 

The Quartz Compositor (formerly Core Graphics Services) is responsi¬ 
ble for providing windowing services for the Classic, Carbon, Cocoa, 
and java application environments. These environments interact 
direcdv with the Quartz Compositor to automatically bring advanced 
windowing features, such as double-buffering and live window drag¬ 
ging, to applications. OpenGL and QuickTime rely on the Quartz 
Compositor to seamlessly mix hardware accelerated 3-D and multime¬ 
dia into a single visually consistent windowing environment. Finally, 
the Quartz Compositor helps create the hallmark Aqua user experi¬ 
ence by generating dynamic drop shadows and transparency effects 
for each open window. 

Quartz 2D 

Quartz 2D (formerly Core Graphics Rendering) is a two-dimen¬ 
sional graphics engine that allows any Mac OS X application to 
create graphics that were previously limited to high-end applica¬ 
tions. Quartz is based on the Portable Document Format (PDF) 
graphics model and features a rich set of drawing functions. 

These drawing functions are fully accessible by both Carbon and 
Cocoa developers. 

Core Graphics API Functionality in Quartz 2D 

The foil power of the Quartz 2D engine is exposed through die Core 
Graphics API. What follows is a breakdown of the advanced features 
you can use to create new and exciting Mac OS X applications. 

Drawing Functionality 

The Core Graphics API contains a comprehensive set of functions 
that give you access to PostScript-like drawing features. Some of 
these features include path-based drawing operations (such as 
Bezier curves), dipping paths, and transformable coordinate spaces 
that allow easy access to rotations, scales, and skews. The Quartz 2D 
engine draws using an advanced sub-pixel anti-aliasing algorithm 
that significantly enhances the visual appeal of both vectors and text. 
Additionally, Quart 2D's alpha compositing ability allows for trans¬ 
parency effects for vector shapes and supports alpha channels when 
drawing bitmaps. Detailed information on the Core Graphics API 
can be found m Inside Mac OS X: Drawing With Quartz , available 


Travis W, Brown is the Imaging Technology Manager for Mac OSX in Apple’s Worldwide Developer Relations. Travis has been involved in digital 
imaging for the past decade , working on various products, ranging from drivers for color printers and digital photographic imaging systems to 
PostScript interpreters. 
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from the Apple Developer Connection web site at: 
http: //developer, apple, com/qua viz 

PDF Support 

The Quartz 2D engine is based on the PDF specification and is 
therefore able to parse and render most PDF files. Using the Core 
Graphics API, it is easy to add the ability to display PDF files to your 
application. This PDF support also allows applications to create PDF 
files by redirecting drawing calls into a file. The resultant PDF file 
can contain all types of graphic content including fonts, text, vec¬ 
tors, and bitmaps. 'ITiese capabilities make the PDF file an excellent 
replacement for the well-worn PICT file, 

Adobe’s Portable Document format, vlj Reference Guide is 
the authoritative source of information on the PDF format. The 
“Graphics" section of the reference guide is particularly useful for 
understanding the PDF drawing model upon which Quartz 2D is 
based. You can find the complete guide at: 

http: //partners, adobe. com/asn/developer/acrosdk/docs/PDFRefpdf 

Color Management 

The Quartz 2D engine works in concert with ColorSync to ensure 
everything it draws is color managed. This tight integration allows 
your application to participate in end-to-end color management 
with minimal effort on your part. At the most basic level, your 
application can programmatically specify' colors in a variety of 
color spaces via the Core Graphics API. Quartz 2D will automati¬ 
cally call on ColorSync to ensure the requested color is matched 
to the display or printer. Color management is also automatically 
used when drawing PDFs and bitmap images. Lastly, the Quartz 
2D engine also has full support for ICC color profiles and render¬ 
ing intents. 

More information on color management and ColorSync can be 
found at: 

http;//developer, apple, comftecbpubsfmacosS/MultimediaGraphics/C 
olorSyncManagericolorsyncmanager.html 

Fidelity 

The Quartz 2D engine is resolution independent and is capable of 
rendering graphics for both screen and print. The Quartz 2D engine 
plays an important role in Mac GS X’s printing architecture where it 
acts as the Raster Image Processor (RIP) for inkjet printers and 
other raster derices. The Quartz 2D engine is also capable 
of converting graphic streams into PostScript code for imaging 
on PostScript output devices. So, applicatioas that use the Core 
Graphics API can easily output graphics to a full range of printers, 
from inexpensive inkjet printers to high-end PostScript devices, with 
excellent and consistent results. 

Resources to Help You Take Full Advantage of Quart 2 

The Quartz technologies web site is die first place you should check 


for the latest information on Mac OS X ? s graphic technologies. The 
Quartz web site, which is pan of the Apple Developer Connection, 
can be found at: 

http://dei eloper, apple, co m/qu a rtzjindex. html 

For compatibility with earlier versions of the Mac OS, Carbon 
applications use QuickDraw' for two-dimensional graphics drawing 
by default. ITiese applications can, however, access Quartz 2D’s 
Core Graphics API. The Quartz Primer was created to help Carbon 
developers understand how to use this powerful tool. The primer 
is available at: 

bttp:/ideveloper apple. com/tecbpubs/macosx/System Overview/ 
devessentials.btmi 

Many Carbon developers have expressed interest in drawing text 
using Quartz 2D T s advanced anti-aliasing. The Core Graphics API has 
basic support for text drawing, though. Higher-level services, such 
as ATSLU and MLTE, have been included in Mac OS X to draw text 
w r hen working with Quartz. More information on Mac OS X’s text 
services can be found at: 
http: i!developer apple . com/intl/fext. html 

Cocoa developers have a “free pass” to access the Quartz 2D 
engine. Three key dasses-NSVIew, NSlmage, and NSBczicrPath- 
call through to the Quartz 2D engine. Developers may discover 
cases, though, in which direedy accessing the Quartz 2D engine is 
desirable. To address this need, the Core Graphics API can easily be 
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Project Builder 
Tips & Tricks 

* The malloc library on Mac OS X has a bunch of features 
that can help you track down memory smashers, buffer 
overruns, and other Stupid Pointer Tricks(tm). Check out 
/Devetoper/Documentation/ReleaseNotes/ 
MallocOptionsMtml to learn how to use these features. 

* Don’t put alE your application's user interface into one nib. 
When a nib file is open all objects are instantiated at once. 
Breaking up your user interface among multiple nibs will make 
your application launch faster and use less memory. It will also 
be easier to reuse part of your application. 

* Interface Builder 

Option Drag knobs: Makes matrices in Cocoa 

Command; Inverts guide activation 

Double Click to open editors 

Shift-arrow: nudge widgets by 10 instead of 1 pixels 

Drag custom views into the document for use as 

accessory views 

Option drag views into New Palettes 







New Mac OS X 
Related Releases 

• Mac OS X 10,0.2 and iTUnes 1.1.1 

Mac OS X 10.0.2 and iTunes 1.1.1 together add the ability to bum 
custom music CDs to Macintosh computers with CD-R drives, Mac 
OS X also features improvements in overall application stability and 
the latest version of the Internet file transfer service (ftpd), which 
features important security improvements. 
httpi/iasu. info, apple . com/swupdates. nsffartn uminlll 81 / 
http://asiLifrfoMpple.com/sufupilates.nsf/artnum/nl2186/ 

• CarbonLib 1,3.1 SDK 

The CarbonLib 1.3-1 SDK (Software Development Kit) for Mac OS X 
is now available to all developers. This SDK provides all the files 
needed to begin Carbon development. Contact Software licensing 
to distribute CarbonLib 1.3.1 with your product. 
http://developer, appte.com/sdk/ 

• Disk First Aid 8-6,1 (US and inti English) 

Disk First Aid 8.6.1 {US and Inti English) is a utility that verifies and 
repairs some problems that may occur on Mac OS Extended format 
hard disk drives. This version of repairs certain types of master 
director}' block damage on Mac OS Extended format volumes, it 
also improves the compatibility of Mac OS Extended format hard 
disks with Mac OS X. 

httpd/asu. info. apple, com/sit f updates. mf/artn u m/nl2l 8 7/ 

• Software Update 1,3.1 

Software Update 1.3,1 is a multicountry update for the Mac OS X 
Software Update control panel. 

httpd/mu. info. apple. com/swupdates. nsf/artna m/n 121 65 / 

• Darwin 1.3-1 

Darwin 1.3.1 is the open source core of Mac OS X. This open source 
project allows developers to customize and enhance key Apple 
softw are. The Darwin kernel is based on FreeBSD and Mach 3-0 
technologies and provides protected memory and pre-emptive 
multitasking. 

http;//www, opensource , apple, com/projects/da rwi n/ 

Developer Documentation 

The following new and updated documentation is available to 
help with successful Mac OS X application and peripheral 
development at: 

http: //developer apple . comftechpuhsf 

iBook Developer Note 

TN2018 - Importing animated GIFs 

TN2017 — Using launch Services for discovering document binding 
and launching applications 


QA1034 - How to define a plst resource in a ,r file 
QA1033 - Targeting DebuggingCarbonLib asserts 
QA1032 - Late breaking news for the MacsBug gdb plugin 
QA1031 - OpenGL Texture Sharing Between Contexts 
QA103Q - Getting NSWindow T s toolbar actions to show up in 
Interface Builder 

QA1029 - How to get custom views to show up in NSToolbarltems 

QA1028 - ICLaunchURL, "file;///” URLs and Mac OS X 

QA1027 - Improving ATSUI text drawing performance 

QA1026 - Calling AppleScript from an Application 

QA1023 - The installer turns my application into a folder 

QA1022 - Where should I install my help book, and how does Help 

Viewer locate it? 

QAI02 I - Cocoa-Java quit/cancefquit header bug in Mac OS X 10.0 
QA1015 - Why am I drawing directly to the screen? 

QA1011 - How do 1 use QuickDraw with CGDirectDisplay? 

QA1010 - SynCGContextOriginWithPort 

QA1009 - Why are my Core Graphics calls drawing updside down?— 


Sample Code - More than thirty new Mac OS X code samples w^ere 
posted to the ADC web site since the last issue. Please visit the URL 
below for a complete list of sample code. 
http://4evehpmapple.com/samplecode/ 


Did You Know? 

Quartz Documentation 

he technical writers at Apple are hard at work 
preparing Quartz documentation for software 
developers. Already available is the “Quartz 
Primer,” a short document that summarizes Quartz 
features and concepts, discusses how to incorporate 
the graphics-rendering capabilities of Quartz into 
Carbon code, and includes examples of using Quartz 
APIs. You can get this document at 
http://developer.apple.com/techpubs/macosx/System 
Overview/devessentials.html 

In the works is inside Mac OS X: Drawing With 
Quartz. This book is intended to be an essential 
resource for any software developer interested in 
learning about and using the advanced two- 
dimensional graphics capabilities of Mac OS X. It will 
discuss the following topics: 

• graphics contexts, coordinates, transformation 
matrices, graphics state, and transfer modes 

* transparency and anthaliased drawing 

* drawing shapes with paths 

* drawing text 

• working with color 

• drawing images and PDF documents 
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Beyond QuickDraw: Quartz 

Continued from page 63 


called from Cocoa and used in conjunction with a 
Cocoa View. Information contained within the Core 
Graphics header hies is a good place to start. The 
header hies can be found at: 

/System/LibraryfFrameworks/ApplieationServicesJr 
ameworkIFra meworksiCo reCraphicsfrani ework/ 
Headers 

Other Quartz APIs of Interest 

In addition to the Core Graphics API, Quartz also 
contains some specialized APIs that may be of inter¬ 
est to you. 

Remote Operation 

This API interacts with Quartz Compositor to 
enable applications to capture screen contents 
and push keyboard/mouse events into the system. 
If you are designing a screen capture program, a 
remote access application, or an accessibility aid 
then you should check out the CGRemote- 
Operation API. A well-documented header file Is 
located at: 

/System/Idhrary/FramewoHss/ApplicationServicesJr 
ante work/Frametvorks/Core GraphicsJmm ework/ 
Headers/CGRem oteOpe ration. b 

Direct Display 

This .API allows applications to get direct access to 
die screen. Applications, such as games, can use 
this API to capture the display, set the display reso¬ 
lution, and gain direct access to the frame buffer. 
Information on CGDirectDisplay can be found in 
the header hie that is located at: 
/System/library/Frameutorks/ApplicationSenlcesfr 
ante u 'orkiFrameiiorksiCoreGraphics.fram ework! 
Headers/CGDi rectDisplay, h 

Summary 

Quartz is a powerful new r graphics system that 
performs two vital roles in Mac OS X, The Quartz 
Compositor provides windowing services to all of 
Mac OS X. The Quartz 2D engine is responsible 
for creating visually rich graphic content on¬ 
screen and ensuring high-fidelity output to all 
classes of printers. Of primary interest to develop¬ 
ers is the Core Graphics API. This API offers devel¬ 
opers exciting opportunities to create new and 
powerful graphic applications by leveraging the 
Quartz 2D engine's PostScript-style drawing, color 
management, and PDF file support. 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 

visit the developer Events page at: http;!/developer* applexomievents! 

Training and Seminars 

Rlcom Offers Mac OS X Developer Training Online 
R/com, also known as Media School, has partnered with Apple Developer 
Connection to create online training for Mac OS X developers. The first cours¬ 
es include 'Application Development for Mac OS X,” "'Carbon Development for 
Mac OS X/' and “Cocoa: 'Hie Object-Oriented Application Solution.” Check out 
<http://Ww.mediaschooI.com/adc> to take a free virtual seminar, learn 
more about current and upcoming courses, and find out about the significant 
discounts offered to Premier. Select, and student members of the Apple 
Developer Connection. 
bttpjfwww. tnediaschool com fade 

Apple iServices 5-day Cocoa Training 

For application developers who w r ant to learn how to develop Mac OS X 
applications using Cocoa, Apple iServices offers a five-day comprehensive, 
hands-on Cocoa training course. This course uses real-world examples and is 
perfect for developers who have a general understanding of object-oriented 
concepts and practical experience with the C programming language or a C- 
derived language (Object-C, Java, or C+ + ) The course costs US $2,495 
http://www. apple . comfiservfcesitecbnicaltrain ingicocoadev, him l 

AppleScript Intensive Workshop 

Four-day interactive experience for intermediate and advanced scripters June 
4-7 in Chicago IL (DATES CHANGED) June 12-15 in Santa Monica CA 
bttp.Hwww. waive i ent, comlintensive. btml 

Developer Related Conferences 

QuickTime BootCamp Authoring Conference in Europe 
Held June 6 and 7 in Cologne, Germany 
bttpPiwum qtbooteamp* de 

Macllack Conference Dearborn. Ml 
June 21-25 

MacHack, in its sixteenth year, remains centered around cutting edge soft- 
w^are development. MacHaek’s uniqueness derives from the informal feel and 
the LIVE coding that occurs around-the-clock during the conference, 
http : Hwww. macback. comI 

MACWORLD Expo i, New York 2001 

July 17-20 in Jacob Javits Convention Center, NYC 

Discounted exhibitor packages available 

bttp:f/developer apple . comfmktfm ivny200L htm l 








MAC OS X 


By A ndrew Stone 


File Formats and Legacy Object 
Unarchiving 


An Object Lesson for Programmers 


Most programs write data files. This is an article about how 
we used to write objects, some of the trouble we got into later, 
how 1 got our of that trouble, and a description of how r to write 
a file with a format that will endure almost forever, Lie forward 
and backwardly compatible, and be universally parseable. 

A long time ago in a place not too far away, disk space was 
a very precious commodity - witness my first mass storage 
purchase in 1986: a 10 Megabyte external SCSI hard drive for my 
Mac-K The cost was $600, Now you can get a 30 gig drive for 
around $130, three thousand times the amount of storage for a 
quarter of the cost. Back in those early dark days, compressed, 
machine-only readable binary streams made sense. And if space 
is still an issue because of scale, binary streams are still useful 
But when it comes to life cycles of software and maximal 
interoperability between applications, a plain English table of 
keys and values that humans can read (such as XML) is a 
compelling archival format because documents are backwardly 
and forwardly compatible. What this means is that earlier 
versions of your program can open documents produced by 
later versions, although some information may be lost. 

Moreover, you do not force your users into unacceptable 
proprietary data formats. Instead, Cocoa developers should 
support waiting their objects in XML as a combination of 
dictionaries, arrays, strings, values and data. Data is the catch all 
for objects which cannot decompose into die simpler types or 
are best represented as an object stream, such as an NSColor or 
an NSTextStorage, The CoreFoundalion classes which serve both 
Carbon and Cocoa can write standard objects as either UTF8 
XML or as an even easier-to-read format, the old style NeXTStep 
property list: 

l 

BitDepth = 520: 

DocuraentHTML — I 

BGCoIdt = <040b7479 70656473 74726561 6d81Q3e8 
84014084 8484074e 53436f6c 6f72Q084 84084^53 4f626a65 
6374D085 84016301 84046666 6666833f 4ccccd83 3f4ccccd 
010186); 


CenlerlnTable “ YES; 

Coalesce = 0: 

ColorFromView = NO; 

HTMLGlass “ DocumentHTML; 

Now, compare that readability and compactness to the 

XML version; 

<?xmi version^'* 1.0" encoding =,, UTF-3 H 7> 

<IDQCTYFE plist SYSTEM 

"■file; I / localhost/System/Library/DTDs/PropertyList .dtd"> 

<plist versian="0.9") 

<dict> 

<key>BitBepth</key> 

<atring)520</string) 
dictionary) 

<key>BGColor</key> 

<data> 

BAt0eXBlZHNOcraVhbYED6IQBQI£EhAdOU0NvbG9yAISECE5 , IT2JqZWN0AJWEAWMDhAJiii 

ZgEBhg,— 

(/data) 

<key)CenterlnTable</key) 

<string>YE5</string) 

<key>Coaiesce</key) 

<integer)0</integer) 

<key)ColorFromViev</key> 

<st ring>ND</string) 

< key >HTMLCia s s </key) 

( at ring)DocumerjtHTML</string) 

XML adds the ability to write dates and number values to 
the standard set of dictionary, array, string and data, 
/Develo per/ Doc u mentation/Re I ease Notes/Foundation. h t m l 
explains this and other nuances about writing XML. Currently, 
we prefer the old style property list for cross-platform 
compatibility with Open Step and Mac OS X Server versions of 
our applications. 


Opening the Vault 

The reason I know that property lists is the way to archive 
data is the amount of work ] have had to do to convert old 
NeXTStep 3 object streams into something openable by 
Create® for OS X. For almost all AppKit classes, the ability to 
open lheir original NeXTStep counterpart class is already 
provided by Apple, For example, an NSColor can open an 
NXColor struct, and NSPrintlnfo can open archived Printlnfo 


Andrew Stone CEO of Stone Design Corp - www.stone.com, lias tw ice the number of ZPG children and farms chiles and software from a tower 
along the Rio Grande in Albuquerque New Mexico. 
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objects. Where this all falls down is in View: NSView cannot 
open View objects because the Objective-C List object does 
not have an -initWithCoder: and subviews were stored in a list. 
This can be verified by reviewing the Darwin source code. 
This affected NeXTStep applications such as Create, NeXTStep 
Draw, and other applications which stored the data model in 
a binary typed stream as a list of graphics owned by 
GraphicView, a subclass of View: 

_typedstr eamA_CN_i_N_@NNN Print Info 
Black_VeaverNN_NeXT 40Q dpi Level II FrinterNN_goat 

In hindsight, this is a stupid architectural decision - you 
shouldn’t comingle data that Forms the content of your 
document with the way you display that data. And, if you are an 
object purist such as this wizened old timer, you are not content 
until the view, the model and the controller components are all 
neatly separated. Luckily, if you use Cocoa's NSDocument 
architecture, you will automatically do the right thing! 


1. Click “Targets" 

2. Select your application 

3. Click on the “Applications Settings" in the Target inspector pane 

4. Click on your document type 

5. Add the new extension to be opened in the Extensions field, 
separated by spaces 


I] sfl 

■ 

i 

A find 4 i a Run | Debug 

I 

* * @ Targ« Cftate tApplJcitlo^t 

a a □ 


f File. 1 Build Phases 1 Build Settings f Application S.tllngs T ibuutibtf \ 

Slnipkt Expert 


V Document Types 

* 

r 


Name Role 

Extensions Types 


Stone Design Graphic Format Editor 

ertft create SDCD 


Figure L Just add the file extensions of the legacy files to be opened . 


The File Upgrader 

Create has a separate, included application named 
“CreateDocUpgraderapp”, By adding a Copy Files,., phase to 
your Froject Builder project, you can include other builds and 
products in your main application, such as the 
CreateDocUpgradenapp, Create registers for the old NeXTStep 
Created file extension, “.create” in Project Builder; 


Felt Tip 

Sound Studio 



Record and Edit Audio 

with a sound editor designed for the Mac. 

Sound Studio will allow you to make quick edits with an 
interface as easy as a text editor Add polish to recordings 
with fades, normalization, and edits. Create your own mixes. 
Transform them with effects. 


Sound Studio features 

* up la 16 hiLs, 2 channels, and 66 kit* 

* up to 2 GB of audio 

■ AIFF, Sound Designor 2 , WAVE, 

System 7 Sound, and QuickTime import 

* edit with sample accuracy 

* fade, amplify, normalize, and invert 

’ delay, echo, reverse, and swap channels 

* smooth and emphasize 

* resampEe and pitch shift 

* snap to zero crossings, snap to grid 


$35 

Sound Studio 

download free 14-day trial 
or order online at 

www.felttip.com 

QuickTime rs a trademw^, uied_iiPKfer ^cersa _ _ price m 05 ttollunt 


Felt Tip Software, 807 Keely Place, Philadelphia PA 19128-232G, USA 



When a file is double-clicked. Finder will ask your app to 
open it. Your NSApplication s delegate class implements the 
following method to call on the included upgrader application; 

- [BOOL)application:(NSApplication *)sender openFile:(NSString 
)path 

[ 

NSString *ext = [path pathExtelision]; 
if ([ext isEqualcreate"] 5 t 

NSString ^upgrades = [[NSBundle mainBundle] 
pathForResource:@ w CreateDocUpgrader* ofType:@*app H ]; 
if (upgrader) I 

return [[NSWorkspace sharedWorkspace] 
openFile;path withApplication:upgrader] : 

I else 

NSRunAlertPanel[UPGRADER_TITLE,UPGRADER_MSG.OK.NULL,NULL); 

] else 

The Upgrader is launched and asked to open the legacy file. 
In the Upgrade rs NSApplication 1 S delegate, you implement: 

■ [BOOL)application:[NSApplication Usender openFile:(NSString 
*)path 

I 

return [self openLegacyFileAndAutoSave;path] ; 


We want to convert the file and then open it with Create 
when it completes: 

[BOOL)openLegacyFileAndAutoSave:(NSString 1 )file; 

I 

// get a now, unique file name based on the original name: 

NSString *neuMame = [self newFileNameWithPath:file]: 

If [ [[self dactunentFromFile:file] saveFileToPath:newName] 

3 I 

return [[NSWorkapace sharedWorkspace] openFilemewName 

withAppiication:{2TCreate 1 ’] : 

I 

NSRunAlertPanel(OPEN, GANNGT_OPEN_MSG, OK, 

NULL, NULL, file,newName): 
return NO; 
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So, the real guts of the upgrader is the ability to read a 
typed stream by implementing mitWithCoder: in all classes 
contained in the typed stream, and then to have those objects 
create an English property list representation, that is, the 
property list format that Create now uses. For the most part, 
you map the old classes to the new NS* classes by invoking 
a little rewiring magic in NSUnarchiver, Early in the launch 
cycle (applicationWillFinishLaunchingi For example), include 
code like this: 

[NSUnarchiver decoded a ssName :@"PrintInfo tt 
asGlas£NaiDe;@ , *NSPrintIrifo' 1 ] ; 

So, when the unarchiver hits the class named “Printlnfo” in 
the object "typed stream*, it will instantiate an NSPrintlnfo 
object, which knows how to open the older versions of this 
object in its -initWithCoder:( NSUnarchiver *)unarchiver method. 
For Create documents, we rewired the following: 

- (void)applicationWillFinishLaunching:(NSNotiflcation 
*}notification [ 

// Some classes just work by remapping: 

[NSUnarchiver decodeClassNamePrint Info* 
asClassNamei@"NSPrintlnfo*]; 

//we need to be able to unarchive NSImage's - and they just work as well! 

[NSUnarchiver decodeClassName:@"NXIinage" 
asGlaasNainejI&TJSIiiiage*] ; 

[NSUnarchiver d ec o deC1as &N ame:@”NXIma ge Re p” 
asClassName;@'NSXn»geRep"]; 

[NSUnarchiver decodeClassName :@"NXBitmapIniageRep* 
asClassName: GrNSBitmaplmgeRep* ] ; 

[NSUnarchiver dec odeClas sNatne:@"NXCachedImageRep” 
asClassName: @*NSCachedIinageRep"]; 

[NSUnarchiver decodedassName:@"NXEPSImageRep* 
asClassName:@"NSEPSIiDage.Rep" f ] : 

// we need our own List reader 

[NSUnarchiver decodeClaaaName:@”List" 
asClassNajne:@”MyList ia ]; 

// the classes NOT openahle by Darwin/QS X: 

// we’ll write our own versions: 

[NSUnarchiver decodeClassNaroe:@"View" 
asdassNaine :@“MyView“] ; 

[NSUnarchiver deeodeClassNamei©"Window H 
aaClassNaEne:@"Hy r Window"] : 

[NSUnarchiver decodeClassName:©"Responder” 
asClaasName:@"NyReEponder w ] ; 

// Some private dass we have to be able to read: 

[NSUnarchiver decodeCIasaNaiiLe:@ f+ PSMatrix rt 
asClassName:@*MyPSMat rix *]: 

) 


Through trial and error handling, I figured out what View 
and Window^ were trying to read. When the Unarchiver reads 
through the stream, it checks to see what the next type archived 
is, If that is different from what you are trying to read, an 
exception is thrown with a message that explains what it 
expected versus what you attempted to read, I usually put a 
breakpoint in NSExceptton’s raise, so 1 can quickly backtrace to 
the line of code which caused the exception. To set this 
breakpoint in PBX's debugger, pause the execution of the 
program, and enter: 

br -[NSException raise] 
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Because we don't really need an NSView or NSWindow, 
simply the list of graphics stored by the View subclass, we are 
only trying to read through die stream, keeping in synch with 
the objects therein, so we can get to our data model contained 
by the view. Here are minimal versions of the classes you will 
need to read old NeXTStep object streams: 

©interface MyList : List 
©end 

©implementation MyList 

- (id)initVithCoder; (NSCoder *)aDecoder 

[ 

int version = [aDecoder versionEorClassName:@ ,, List"] ; 

RSZone *zone = [self gone]: 

NS_DURIHG 

if (version = 0) [ 

[aDecoder decodeValueOfObjCType;"i" 
at:kmaxElements]; 

[aDecoder decodeValueOfObjCType: H i" 
atifirmimElements]; 

dataPtr = (id *} NSZoneMalloc (zone, 
numElements*sizeof(id)); 

EaDecoder decodeArrayOfObjCType:"©” count;numElements 
at:dataPtr]; 

} else f 

[aDecoder decodeValueOfObjCType;"!* at:&numElements]; 
maxElements = ntimElemeuta: 
if (nimiElements) I 

dataPtr = [id *) NSZoneMalloc [zone, 
numEieraents*sizeof[id)): 

[aDecoder decodeArrayOfObjCType:*®* 1 
c aunt:numElement s at:dataPt r]; 


RS_HANDLER 


NSLogf©"threw exception reading List; : 

,[loca lE xception name]. [localExcoption reason]): 
MS_£NDHANDLER 
return self; 


©end 

©interface MyResponder ; Ohject 

I 

id nextResponder; 

id _reserved; 

1 

- (id)initWithCoder:(NSCoder *)coder: 

@end 

©implementation MyResponder 

■ (id)initWithCoder;(NSCoder NaDecoder I 

nextReaponder = [aDecoder decodeObject]: 
return self: 


©end 


©implementation MyView 
// we do use tiie frame and bounds: 

- (NSRect)frame I return frame; I 

‘ (NSRect)bounds I return hounds: 1 

- (id)initWithCoder:CNSCoder *)aDecoder 
t 

float f; 

unsigned int version = (aDecoder 
versionForClassName:©"View"] i 

NS_DtIRING 

(super initWithCoder:aDecoder] ; 

[aDecoder decodeValueOfObjCType:"f" at:&fl; 
frame - [aDecoder decodeRect]: 
bounds = [aDecoder decodeRect]; 
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superview - [aDecoder decodeGbject]; 
window “ [aDecoder decodeObject] ; 

IaDecoder decodeValuesOfObjCTypes:"@ss@" t Ssubviews, 
frvFlags, &_yFlags, &_drawHatrix]: 

US_HANDLER 

NSLog(@"threw exception reading View: W : 

,[locfllException name], [localExeeption reason]); 
MS_ENDHAHDLER 
return self; 

I 

Send 


^interface MyWindow : MyResponder 


l 

NSKect 

id 

id 

id 

id 

id 

id 

id 

int 

int 

float 

struct _wFlaga I 

#ifdef _BIG-ENDIAN_ 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
if else 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
tfendif 
1 

struct _wFlags2 I 

#ifdef ._BIG_ENDIAN_ 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned Int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
tfeiae 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 


frame; 

contentView; 
delegate; 
firstResponder; 
lastLeftHit; 
lastRightHit; 
counterpart; 
fieldEditor: 
winEventHask: 
windowNum; 
backgroundGray; 


style: 
backing:2; 
buttouMask:1; 
visible:1; 
isMainWindow:1: 
isKeyWindow:1; 
isPanel:1; 
hideOnDeactivate:1: 
dontFreeUhenClosed:1; 
oneShot:L; 

oneSkot:1; 

dontFreeWhenClosed:1; 
hideOnDeactivate:1: 
isPanel:1; 
isFeyWindow:1; 
isMainWindow:l; 
visible:1; 
buttonMask:3: 
backing:2; 
style;4; 

wFlags; 


deferred;1: 

_cursorRectsDisabled;lr 
.fiaveFreeCurserRects: i; 
_validCursorRects:1: 
docEdited:1; 
dynamicDepthLimit:1: 
_worksWhenModal:I; 
_limitedBecoineKey: 1; 
_needsFIush:l: 
_newMiniIcon:1; 

_igno redFirstMouse:1: 
_repostedFirstMouse;1; 
_windowDying:1; 
_tempHidden:1; 
_hiddenOnDeactivat e:1; 
_fi©atingFaftel:l; 

_f!oatingPanel:1; 
„hiddenOnDeactivate:1: 
_tempHidden:1; 
_windowDying:1; 
_repastedFitstMouse:1: 
_igtioredFirstMouse: 1 r 
.RESERVED;1: 
_needsFlush:1; 
_limitedBecomeKey: 1: 
_worksWhenModal:1; 
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The MacTech CD-ROM with 
THINK Reference is the 
essential reference resource for 
Macintosh programmers. This 
CD includes the THINK 
Reference personal database 
system and a wealth of 
Macintosh programming database^ 
featuring over 160 issues of the 
journal of Macintosh 
programming — MacTech Magazine* 
This release also features the 

f 

THINK Reference Compiler, which 
allows you to compile HTML files 
into your own compact, searchable 
THINK Reference databases* 
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unsigned int 

dynamicDepthLimit:1: 

unsigned int 

docEdited:1: 

unsigned int 

.validCursorRects:1; 

unsigned int 

_haveFreeCursorRects:1 

unsigned int 

.cursorRectaDisabled:1 

unsigned int 
#endif 

deferred:1; 

1 

wFlags2; 

id 

_borderView; 

short 

_disp lay Disabled 

short 

.flushDisabledi 

void 

*_cursorRects: 

id 

.trectTable; 

id 

_invalidCursorView; 

id _miniIcon; 

void 

^private; 


i 

©end 


©implementation MyWindow 
- [id)InitWithCoder:(NSCoder *)aDecoder 

i 

unsigned int version = [aDecoder 
versionForClassName;©"Window”); 

NSRect frameRect; 

char *title: 

NSZone *zone = [self zone]: 
short flags: 

NSLPURING 

[super initWithCoder:aDecoder]: 
frame = [aDecoder decodeRect]: 
if [version = 0] I 

[aDecoder decodeValuesQfObjCTypes:"§©ifss*" . 

&contentView. ^counterpart, kwinEventMask, &backgroundGray. 
&wFlags. &wFlags2. Stifle] ; 

] else if [version = l) [ 

[aDecoder decodeValuesOfObj CTypes: w @@if a s■* *, 
icontentViev* ^counterpart. &winEventrksk t &backgroundGray t 
SwFlags, &wFlflgs2, fctitle*&_raini!con]; 

I else if (version >= 2) I 
NSColor *tmpColar; 

[aDecoder decodeValuesOfObjCTypea:((version 4) ? 
"©@ifES*@s M : M @@ifss'*s"). &cont«ntView, Scoutfterpart. 

&winEventMask, fcbackgroundGray, fcwFlags, &wFlags2, feitlfi* 
&_miniIcon, kflags): 

tmpColor = [aDecoder deeodeNXColor]: 

] 

if (version >= 3) \ 

NSSize min, max: 
char c; 

[aDecoder decodeValueOfObjCType:V at;&c]; 
if (c & 1) min = [aDecoder decodeSize]: 
if (c & 2) max = [aDecoder decodeSise]: 

\ 

delegate = [aDecoder decodeObject]: 
firstR.espander = [aDecoder decodeObject] ; 
frameRect = frame; 

FrameRect.origin.x = FrameRect.origin.y = 0.0: 
NS_HANDLER 

NSLog(@"threw exception reading Window: : 

%©", [iocalException name]. [localException reason] 1 ]; 
NS_ENDHANDLER 
return self; 


©end 

// this is two matrices - probably lor view rotation - but our view cannot be rotated, so 
we read and go on... 

©interface MyPSMatrix: Object 

I 

float matrixElements[12]; 
unsigned short flags: 


©implementation MyPSMatrix 
- (id)initWithCoder:(NSCoder *)aDecoder 
( 

float f: 

unsigned int version = [aDecoder systemVersion]; 

NSJOTING 

if (version < 901) ( 

int temp: 

[aDecoder decbdeArrayOfObjCType:"f n count:12 
at ^matrixElements] : 

[aDecoder decodeValueOfObjCType;"!” at:&temp3; 

1 else ( 

[aDecoder decodeArrayOfObj CType:” f ” count:12 
at: 6matrixEleinents); 

[aDecoder decodeValueOfObjCType: "s" at:&flags]; 


MS_HANDLER 

NSLog(©"threw exception reading PSMatrixi %@ : 
[localException name]. [localException reason]); 
NS.ENDHANDLER 
return self; 


©end 

So, the preceding code lets you get at your own objects, but 
consider the case where you have legacy files from OpenStep as 
well as NeXTStep. In OpenStep, we use the NSView hierarchy, 
so if you have custom class which can open both NeXTStep and 
OpenStep typed streams, then youll have conditional code at 
the top of the -initWithCoder: 

GraphicView:NSView 

- (id)initWithCoder:(NSCoder *)aDecoder 

t 

int version = [aDecoder 
versionForClassName:GraphicView"|: 

if [version < 400) Mf NeXTSTEP... 

// we don't ready use too much of what's in a view 

//An NSView cannot open us up - therefore, we'U use our custom My View to imitate: 
id oldSfyleView = [[MyView allocjinitj; 

NSLog[©"attempting to read NEXTSTEP object file*): 

[oldStyleView initWithCoder : aDecoder] : 
if we 11 grab two ivars we care about; 

_frame = [oldStyleView frame]; 

.bounds = [oldStyleView bounds]; 

H if you needed more Into from the View, just implement more methods in 
// My View, and query hen.. 

] else [super initWithCoder:aDecoder]: // An OpenStep 

object file 

// now. the normal unarchiving follows, which includes reading the list of graphics 


Now, the Graphic View stored a list of graphics - so we want 
to be able to convert the old List object into a new r 
NSMutableArray, That trick is achieved by this invoking line and 
NSMutahleArray category method initFromList; 

.graphics “ [[NSMutahleArray allocWithZone:[self zone]] 
initFromList:_gtaphics]: 

©interface NSMutahleArray(Compatibility) 

- (id)initFromList:(id)aList; 

©end 

©implementation NSMutahleArray(Compatibility) 
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Marketing Rule no.I 


MAKE YOUR PRODUCT EASIER TO BUY, YOU'LL SELL MORE OF IT. 


You may have developed the best software in the world, but if nobody 
knows about it, or can find it, you won't sell much of it. With eSellerate, 
your application literally sells itself. Providing your customers with the power 
of instant gratification. And providing you with an opportunity 
of nearly limitless potential, w w w. e s e 11 e r a t e . n e t 6 6 T Q t 6 
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• (id)initPromList:(id)aList 

1 

irit i. count; 

if ( [aList respandfiTaSfilector:0flelector(isKindOf:)] && 
[aList isKindQf:[List class]] ) 1 

count - [aList count]; 

[self InitVithCapacIty:count]; 
for (i = 0: i < count: i++) | 

[self addObject:[aList objectAt:!] ] ; 

} 

j else if ([aList isKindOfClass:[NSArtay class]]) { 
return [self initWithArray:aList); 

] else { 

/* should probably raise */ 


return self; 

] 

©end 


Writing the Property List 

So, with this code, you should be able to unarchive 
NeXTStep data models that included List, View, Responder, and 
Window classes. The one ‘caveat emptor 1 is that NXDataLink, 
and family classes, do not really have a corresponding class in 
the AppKit, so if your application allowed automatically 
updating embedded links, you are going to have to do more 
reverse engineering! Meanwhile, this whole mess could have 
been avoided by storing your data as a dictionary, with keys and 
values For each instance variable. An excellent example of the 
use of property lists as an archive format is provided in the OS 
X Developer release in Sketch: 

/Developer/Examples/AppKit/Sketch. 

Once you have the legacy objects read into memory, then 
you write them out in the property list format: 

static NSString *5KTGraphicsListKey = ©"GraphicsList": 
static NSString *SKTDrawDocuiaentVersionKey - 
©"DrawDocumentVersion": 

static int SKTCurrentDrawDocumentVersion = 1; 
static NSString fSKTP tint Inf oKey = ©"Printlftf o' 1 ; 

- (NSDictionary 4 JdrawDocumentDictio-naryForGrapbics:(NSAcray 
*)graphics I 

NSMutableDictionary ‘dot " [NSMutableDictionary 
dictionary]; 

unsigned i. C = [graphics count] ; 

NSMutableArray ‘graphicDiets 11 [NSMutableArray 
arrayWithCapacity:t]: 

for ti-0: i<c: i++) [ 

[graphicDicts addObject:[[graphics objectAtIndex:i] 
propertyLlstRftpreseatation]1: 

I 

[doc setObject:graphicDicts forKey:SKTGraphicsListKey]: 

[doc setObject:[NSString stringWithForraat 
SKTCu rrentDrawDocumentVersion] 
forKey:SKTDrawDocumentVersionKey]: 

[doc setObject:[NSArcbiver 
archivedDataWithRootObject:[self printlnfo]J 
forKey:SKTFrintInfoKey]; 

return doc: 


To write it out as ASCII, get the dictionary and return the 
NSDatai 


■ (NSData dravDocvmentDataForGraphics:(NSArxay *)graphics l 

NSDictionary ‘doc = [self 
d rawDocumentDictions r y F orGr aphic s:graphice]: 

NSString ‘string = [doc description]: 

return [string dataUsingEncoding;NSASCriStringEncoding] : 

1 

To save the actual file, simply override 
d a taJtepresentationOfry pe: 

- (NSData 4 )dataRepresentationGfType:[NSString *)type 1 

if ([type isEqualToString:SKTDrawDocuiiientType]) I 
return [self drawDocumentDataPorGraphics:[self 
graphics]]; 

] alee.*.. 

1 

Finally* each Graphic subclass needs to know how to respond to 
propertyListRepreseutation - here’s an example: 

NSString ‘SKTlmgeContentsKey = ©"Image": 

NSString t SKTFlippedHorizontallyKey = ©"FlippedHorizoiitally": 
NSString ‘SKTFlippedVerticallyKey = ©"FlippedVertically"; 

- (NSMutableDictionary *)propertyListRepresentation I 

NSMutableDictionary ‘diet - [super 
propsrtyListRepresentation] : 

[diet setObject:[NSArchiver 
archlvedDataWithRootObject:[self image]] 
forKey:SKTImageContentsKey]; 

[diet setObject:([self flippedHorizontally] ? ©"YES” ; 
®"NCn forKey:SKTFlippedHorizontallyKey]: 

[diet setObject:{[self flipped Vertically] ? @ Sh YES” : 

©"NO”) forKey:SKTFlippedVerticallyKey]: 
return diet; 

) 

Because each Graphic subclass encodes its name under the key 
SKTClassKey, Graphic uses code like this to instantiate the 
correct class: 

+ (id)graphicWithFropertyListRepresentation:(NSDictionary 
*) diet: [ 

Class theClass = HSClassFromStringt[diet 
objectForKey:SKTClaesKey]): 
id theGraphic “ nil: 

if (theClass) f 

theGraphic => [[[theClass allocWithZone;NDLL] init] 
autorelease]; 

if (theGraphic) I 
// read all die values stored and reconstitute: 

[theGraphic loadPropertyListRepresentation:diet]: 

) 

I 

return theGraphic: 


Again, refer to the Sketch source code for a full 
implementation of reading and writing property lists. 

Conclusion 

The end result of using property lists as a file format is 
that humans can read them, edit them at will, and open them 
with other applications including earlier versions of the 
creating application. The advantages of property lists very 
much outweigh the only disadvantage which is file size: 
about twice that of a binary equivalent. 

El 
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REALBASIC 


by G.D. Warner 


Beta Testers: What Do Programmers Want? 


The Basics of Testing Macintosh 
Software, Writing Bug Reports, and 
Keeping Developers Happy 

“it was a bug. Dare , ” 

Programmers (especially those named Dave ) really hate to 
hear these words. 

While this article won’t help developers produce bug-free 
code, it will help the people that test the programs developers 
write: the Beta Testers, Well discuss the good (and bad) of bug 
reports, and take a brief look at MacsBug in a sidebar ("Quick 
and Dirty MacsBug”), where you 1 )! learn the six commands one 
needs in use MacsBug effectively. 

Your program is finished. Everything works (or appears 
to).., but before you release it to the (hopefully) paying public, 
it needs to be tested. That's where Beta Testers come in. 

What does a Beta Tester do. anyway? 

"Beta testers am the program and do pretty much 
everything possible in it/’ says a KEALhasic developer who goes 
by the nickname of Squirrel. He continues: 

"Click all the buttons, just mess around, and also use it like 
It is supposed to be used. If they find a bug, they report back 
what happened, what they were doing at the lime of the error," 

Bul ... what kind of information does a programmer need 
from his (or her) testers? 

"Two words: Reproducible results,” says developer Richard 
TheiL "An identified bug is an eliminated bug." 

Words to live by. 

"Exact instructions on how to get the program to misbehave 
will do the job,” Richard continues. “If these can't be obtained, 
the next best thing would be a MacsBug StdLog.” 

StdLog is a text file produced by Motorola and Apple’s 
MacsBug, a debugging tool for Motorola's 68K and the 
PowerPC chips. 

If you've never seen it in action, MacsBug is as close to DOS 
as you 11 ever gel on the Mac (less PC emulators, Linux builds, 


and the terminal in OS X, of course). There are a couple rather 
lengthy manuals on the net that explain how to use it. For one 
of these, check here: 

http://developerapple.com/tools/debuggers/MacsBug/Documentation 

/MacsBugRef_6.2.sithqx 

And here; 

http://www.macfixit.com/reports/MacsBug.shtml 

If you’re testing a crash-prone program and need to produce 
a StdLog file but don't know how, check the Sidebar, It will save 
you some research time. 

Thorsten Lemke, author of “Graphic Convener,” has specific 
requirements for his testers: 

“1 ask my testers for the Following: e-mail a screen shot, a 
MacsBug report, and e-mail the file that produced the errur.” 

Obviously, it's hard to troubleshoot problems with a graphic 
without the original graphic, 

RB developer Peter Jobs, (author of "Monica,” Hefty FTP,” 
and "NewsFindcr"), has a few suggestions on what he w r ants 
from his testers: 

u ] suppose the following sorts of things: 

To actually run the program for some extended period: to 
check that the functions screens do what they look like they are 
supposed to do; to check that the program corresponds to the 
dot's: to hammer the program by trying to input invalid data and 
by running it under load: to think about the programs functions 
and interface and to suggest improvements. Obviously, to report 
your findings! Any other things you might find relevant-I can’t 
think of everything!” 

“All steps necessary to reproduce an error and the 
environment configuration,” Thomas Engelmeier 
recommends. "Best way still is to provide a button that 
extracts 'submittable” data. 11 

Interesting idea: software that can write its own bug 
report-or portions thereof, anyway, A developer who goes by 


G.D, Warner is a Technical Writer, anti lias been using the Mat since 1992, He's been downloading and testing software during that entire time, first 
from local BBSes, then from die internet, and toying with programming (HyperCard, AppleScript, FutureBasic, ObjectBasic, C T C++, Visual Basic, and, 
of course, RealBasic). E-mail him at gtfwarner®ricochet .net. 
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the name of Lord Appolyon (or more simply, Rob) elaborates 
further on this idea: 

“In my standard 'corpus' of libraries 1 use for development, 
one of the more mature things JVe maintained is an interrupt- 
safe logging mechanismhe says. “When enabled at runtime, it 
can record every action (and even every internal “check 
condition” and other event of notice), for the purposes of 
forensic analysis. First and foremost, the logging system is 
designed to be as fast and as non-intrusive as possible-making 
users more apt to enable it when they exercise my program and 
also to be able to ferret out ‘real-time 1 oriented bugs. My model 
was the UNIX syslogO service-which does not exist on 
MacOS (and the one product which bills itself as such needs 
events to function)/’ 

“When I'm trying to fix a bug that’s in a bug report, often I 
can spend 90% to 95% of my time trying to reproduce the bug in 
the debugging environment/’ says William Woody of Panda Wave. 

“That translates to about a day reproducing a bug w hich 
takes as little as a few minutes to a half an hour to actually 
fix/' he continues. “While not all bugs are like this, most of 
them are. So any information I can get from the beta testers 
to help me reproduce the bug in a debugging environment 
will help *A LOT.*” 

"Black Box testing ( where testers do not have access to the 
source code, do not know how it is written/organized, etc.) 
needs to result in detailed steps to reproduce a found bug,” says 
Shawn, a rather anonymous developer. "If the bug is not 
reproducible, even more detailed information is required (what 
other programs are running, System configuration, etc,) As a 
software developer who’s worked with both in-house testing 
departments and end-users who report bugs, I believe this is the 
number one requirement/issue when reporting bugs," 

“I want to see feedback basically, Most beta testers don’t do 
anything at all," Theodore Smith of Elfdata Software says. "From 
those who do give feedback, l like to see someone who 
experiments with very 1 many features of the program." 

He continues: “I like to see determination to continually 
give reports, and to recheck very many things each time there is 
a new version. Obviously they can get away with checking less 
for a new r version, than compared to the next time, but they 
should Lit least check out all the new features properly (and read 
the version history to find out the new ones!), test if the bugs 
they reported have disappeared." 

Game programmers, of course, have slightly different 
requirements. 

"Naturally, it helps to have bug reports. Most beta testers 
will do that much/ 1 says Brandon Ballinger of Flair Interactive* 

lie continues: “But, more importantly, programmers want 
game design advice and suggestions. Is the difficulty right? Was 
a piece of dialogue awkward? Does the user interface make 
sense? Is the player ever confused?” 


Brandon offers a few good suggestions for game testers: 

"Ideally, a Beta Tester would begin playing the game with a 
notepad by their side. Every time there was something wrong 
with the game (be it a bug or a design flaw), the tester should 
write it down. Likewise, if there was something particularly 
impressive, then the tester would w r rite that down as well. 1 
know I’d appreciate receiving an itemized list of specific good 
and bad points," 

Andrew 7 Welch, the self-described “el Presidente” of Ambrosia 
Software concurs with the thoughts of the other developers: 

“Keep a notepad next to your computer to jot Lhings 
dowTHdeficiencies, bugs, or neat ideas,” he suggests, “Put all 
that into a text file in a bulleted format and e-mail it to us," He 
continues: “Get the right tools for the job. Download and install 
MacsBug so you can generate standard logs for the developer to 
use in an effort to figure out why the game/utility crashed* You 
should also probably use a product like Snapz Pro 2, in the event 
that you need to take a screen capture of something to show a 
developer what is going om* 

You can get Snapz Pro here: 

http://www.SnapzPto.com 

David Dunham, lead developer of A Sharp software adds an 
excellent recommendation for game testers: 

“What I liked to see most was saved games (tills was for 
King of Dragon Pass), since that frequently let me reproduce the 
problem. It was surprising how many people wouldn’t bother,” 

James Wilson offers a few more suggestions from a slightly 
different perspective: 

"Let me address tills subject from a standard business 
application (no games, etc ). 

Programmers should provide a standard way of submitting 
bug reports so that they then receive a standard response. Yes, 
do provide a large entry 7 field for comments. 

Programmers should request individual testers work on a 
specific area, user interface, documentation, entry fields, etc. 

Testers should check edit field boundary and entry 
conditions. If a field should only have numbers what happens if 
letters Lire entered? What about special characters? If a field 
should only have a value within a certain range what happens if 
numbers outside the range are entered. What happens on values 
at the boundary?” 

Those were some excellent things to watch for when testing 
a business application. They're even excellent suggestions for 
testing a programming environment like, say, REALbasic. Take 
a look at the latest version of Real Bugs ( Figure 1): 


78 


Beta Testers: What Do Programmers Want? 


MacTuch • June 2001 







f 



Lots of room for comments' would be one way to describe die 
interface of RcalBugs, I asked die folks at REAL Software about it: 

“I believe Geoff (REAL'S CEO) and Jason (head of support) 
came up with the idea,” says Paul Scandariato of REAL Software. It 
leLs users send bug information to us in a structured way - once we 
receive it, we file it in a 4D database where it’s later processed, 
assigned a bug number, and entered into our main database.” 

Sometimes a tester can go too far,..telling the programmer 
how to write the code for his (or her) program is not a good 
idea, for instance. 

"I mean when they obviously have no clue what they are 
talking about,” says jimbo, “Ninety-nine percent of our testers 
couldn't write “Hello World!” let alone disassemble anything. 
Their job is to test our software and report bugs, not play 
programmer for a day." 

Richard Wesley of Electric Fish, Inc. has a slightly different slant 
on tliis subject: 

“By the same token I am a lousy tester, and while I get annoyed 
with the booeheads who don't know the basics of their job ( Le. how 
to communicate results), I would find it similarly presumptuous to 
tell diem how to do theirs. We can all agree on doc umentation 
protocols and testing methodologies, but isolation is an art. one that 
is not respected nearly enough.” 

.. .and then, of course, there are the. shall we say, “less than 
useful" bug reports. 

Jimbo tells of a bid bug report he once found in his In box: 

“What really gets me is a bug report like this: 

£ I found a huge bug in your app!l Click the main menu over 
here. Then pull this menu down. Look what happens”!!' 

Like 1 was looking over their shoulder as they did it.” 

Not even RealBugs can help with a report like that one. 

William Woody of Panda Wave tells a Tale of Bad Bug Reports: 
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Eat your vegetables. 
Exercise every day. 
5? Port to Mac OS X. 

C Call your mom. 


| All of these are good for you. 

! We can make one of them easy. 


Since 1989, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That’s been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's frame Maker to NEXTSTEP and Sun's Concurrence to OpenStep/Solaris. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server, 

• Serious drivers: We ported 3dfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We’ve written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


M )> 


1 he Omni Group 




2707 Northeast Blakeley Street 
Seattle, Washington 9810S-3118 
www.omntgroup.com/consulting 


saies@omnlgroup.com 
800.315.OMNU201 
206.523.4152x201 


tar CSX. NlfXTSTlP, and OpenStep are trademarks of Apple. Acn.'txut and FraaueXfakeraro trademarks of Adobe 5>steim, hit. Quake and Doom are trademarks o!' id Software, Rolarw and Goncumemv are 
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' The ’worse* hug reports are the ones which are 
like 'well, sometimes when I type in the document, it 
crashes.* Typed what? What happened before you 
typed? How did it crash? What files were open? What 
else w T as running? This is a useless bug report, as it 
requires me to either develop ESP or read the mind of 
the tester, or exercise ’every possible combination of 
events* which involves typing-something which could 
take me years to do. 75 

Bill had another nightmare to relate: 

41 Or the worse: once someone told me my 
application w r as completely unusable and not at all 
ready for shipping. I’m thinking the application won’t 
even start on his machine, and, as it crashes, it’s calling 
up his friends via modem and yelling audio- 
synthesized curse w r ords. Turns out he was 
complaining about a typo in the startup splash 
window, and, on seeing the typo so early on, never 
bothered to actually exercise the program. After all, if 
tliere is such a simple mistake this early on, how many 
other bugs are there In the application? (’sigh*).” 

Lord Appolyon’s sysiogO idea helps out in this area: 

“It greatly diminishes the *bs’ factor of ‘OK, what 
exactly did you do, etc?’-the log entries are 
timestamped with millisecond precision, so time 
ordering and sequencing are trivial to establish. At 
maximum loglevel, all routine entry/exit-points are 
logged with parameters and return values,” 

I think Ill have to talk to Lord Appolyon—er, Rob- 
some more on this.,, 

Owen Strain has a request for developers everywhere: 

“Descriptive/Instructive error messages. If an error 
message is reporting a known bug, then it should tell 
me so. Error codes are good, because it makes it easy 
to be specific. Tve seen a program that says 'WRITE 
THIS DOWN AND MAKE A BUG REPORT which is 
good except that it was a finished program...” 

Lord Appolyon also has a recommendation for 
developers everywhere: 

to l ’HIGHLY* advise developers to put some kind of 
logging service in their beta software (which can have 
logging levels increased/decreased or switched on/off 
at RUNTIME), This isn't a panacea for all kinds of 
problems; however in my experience it’s allowed me 
to nail the vast majority of ‘operational* bugs,” 

1 test a lot of programs (sometimes unintentionally, 
like a lot of Windows users). Any time I crash while 
using the program, 1 create a StdLog file, write up an 
e-mail explaining what I did to produce the crash, and 
try to do it again after restarting with Extensions off at 
best, or with the Base Set for whichever version of the 
OS Tm using. If the program crashes again, I produce 
another StdLog (this I’ll append to the original StdLog 


file) and e-mail all of this to the developer, along with 
my notes on what I was doing. When necessary, Ill 
include a screenshot. 

“Wow! 1 wish my testers would do *half* the stuff 
you do,” one programmer wrote to me on Usenet some 
time ago. 

Hence, this article. 

In summary, a good bug report should contain the 
following: 

• System configuration (he., “iMac DV SE 400, 192 MB 
of RAM, Mac 05 X.”) 

• A StdLog from MacsBug 

• A complete and well-written description of the bug 
(don’t make the developer have to read your mind!) 

• (For games): a saved game 

• (For graphics programs): a copy of the problem 
graphic 

When testing a new program, here are a few 
suggestions: 

(1) Look at all the menus. Are all the menu items 
spelled correctly? Does anything appear under the 
wrung menu-Open* under ‘Edit,’ for instance? 

(2) Look at the user interface. Is everything spelled 
correctly? Are command-key equivalents improperly 
assigned (i.e., Gommand-A, C, N, O, P, V, W and Z 
used for anything other than 'Select All, 1 -Copy/ ‘New? 
'Open.’ Print,’ ‘Paste, 7 ‘Close Window,’ and ‘Undo 7 )? 

(3) If the program has fields, are they supposed to be 
‘numbers only? ‘Letters only? Are they? 

(4) Does the program have AppleScript support? If so, 
does it work properly? 

(5) Does it conform to the Apple Human Interface 
Guidelines? Not sure? Go here: 
http://www.devworld.appie.com/techpubs/mac/HfGuidelines/ 
HIGuidelines-2.html 

My hope for this article is that anyone who reads 
it and subsequently downloads a new program will 
look at that piece of software differently... and, if 
necessary, will be able Lo submit to the developer a 
useful bug report. 

It was a bug , Dave,,, !! I feel much better admitting 
that now ." 

Uh, sure HAL, sure, 
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MANAGEMENT 


By John C. Welch 

Edited by Ilene Hoffman, MS 


Seybold Boston, 2001 


An Administrator's Eye View Of A 
Publishing Conference 

Welcome 

Seybold 2001 is best described as a conference in 
transition. While the show still proudly proclaims its 
publishing heritage, the show seems to be moving from 
publishing as an end to publishing as a means. Print or 
digital, the output of the data seems to be far less Important 
than what you do with and to that same data. Asset and 
rights management have also taken on a much greater 
importance in this era of Napster and Gnutella, 

Another sign of change was the vendors, and as 
important as w r ho was on the show floor, was who wasn’t. 
The biggest gap was Apple, which adds a touch of irony, 
considering that without Apple, the digital publishing 
industry would be far from what it is today. That is not to say 
there was no sign of Apple at all. In fact, they were 
everywhere. At least 90% of the vendors on the show floor 
had at least one iMac, Cube, or G4 tower showing their 
products in action, and at least half of these were either 
running Mac OS X, or loudly proclaiming imminent 
compatibility with the new OS. Apple did have a room that 
was used for various presentations on OS X, Final Cut Pro, 
iDVD, and OS X’s use of PDF, The session on PDF w r as quite 
well attended. The level of questions from the audience was 
of a technical enough nature to prompt the presenter to ask 
the folks to remember that the World Wide Developer 
Conference is coming soon, and that is a better forum for that 
level of questioning. Apples iSemces group also had a 
booth in support of another vendor, and was talking up their 
WebObjects consulting and services options. 

The other notable absence on the show floor was Quark, 
Instead of their usual impressive area on the show floor, Lhey 
were running their presentations from hotel meeting rooms. 
This was probably a good diing, as Quark 5 is still in the realm 
of “Real Soon Now.’’ Their major keynote announcement was an 


Internet component to Quark Express, dial allows multiple 
people to work on a document, without needing a copy of 
Quark on each person’s computer. While this is a good 
enhancement, die fact is. Quark 4.x is getting long in the tooth, 
and at presents a fairly stationary target for other publishing 
applications, most notably Adobe Indesign. Quark did say at 
their keynote, that they are working at shedding their hard- 
earned reputation for being somewhat insensitive to their 
customers. This was a humorous contrast to the near argument 
that broke out between the CEO of Quark, and a journalist 
during a post-keynote Q & A session on the same topic. 

So, with no floor presence by either Apple or Quark, this 
was pretty much Adobe’s show, and they rook full advantage 
of it. Adobe showcased the newly released Acrobat 5 and 
talked about die upcoming revision to Indesign, Acrobat 5 
boasts a great many new features, such as WebPAV support 
for online annotation and comments on PDF files, more 
support for complex graphics in PDF files, and the long- 
awaited ability to save PDF files as RTF, so that they can be 
more easily edited. The interface to Acrobat has been 
overhauled, sporting more of a Microsoft Office look. Tear-off 
palettes, collapsible palettes, and a toolbar that can be easily 
customized are among the most notable interface changes. 
Thumbnails are also dynamically generated, or can be created 
in a more static mode as in Acrobat 4. Also upgraded is 
integration with Microsoft Office, databases, and other 
corporate computing tools. Unfortunately, only Windows 
users w ill see these new' updates. Although the corporate line 
Ls that some vague limitations in the Mac OS prevent Adobe 
from implementing the Office integration tools in the Mac 
version, the reality is, Adobe doesn’t see a market for this on 
the Mac side, and ihas chosen not to Implement this feature. 

On the surface, there doesn’t seem to be any practical 
reason for Mac shops to upgrade to Acrobat 5 if they need 
integration with non-Adobe productivity applications. Indeed, 
Adobe’s CEO said during the post keynote Q <& A that 90% of 
all Acrobat purchases are Windows customers. This is a bit 
misleading, as most Mac OS Acrobat users don’t even know 


John Welch <jwelch@aer.com> is the Mac and PC Administrator for a weather and atmospheric science company in Lexington, Mass. He has over 
fifteen years of experience at making computers work. His specialties are figuring out ways to make the Mac do w'hat nobody thinks it can, and 
showing drat die Mac is the superior administrative platform. 
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that this capability exists, so don 1 ! know to ask for it. 
However, there are two ways around this issue. The first is a 
set of plugins from Virginia Systems, 
http://www.virginiasystems.com/. These plugins, available in both 
Mac OS and Windows implementations, allow you to 
automatically create linked tables of content, figure tables, 
indices, and other such features. While not the one-click 
integration that Adobe has implemented on the Windows 
side, these plugins give you 90% of the convenience, and 
more functionality than the Adobe tools. The Adobe tools 
only work from Office documents, and are useless on PDF 
files made from other sources, or created without the 
integration tools. The second solution is from Adobe, namely 
FrameMaker, While not a cheap solution, (MSRP of $800 per 
copy), FrameMaker can easily import Word files, and then 
internally create the links, and export to PDF with the links 
intact. The advantage that FrameMaker has over the other 
tools here is that it runs natively on most brands of Unix, and 
is available with floating licenses, so that companies drat are 
running Unix machines have a decent, easy to use publishing 
tool available. This does bring up the other, less noticed 
aspect of Acrobat 5, While they did not directly say there will 
be no more native Unix support for Acrobat beyond Reader, 
Adobe came about as close as they could. 

Finally, Acrobat 5 is not a carbon MacOS application, 
although Acrobat 5 reader is a carbon application. Questions 
to when Acrobat 5 will be available as a carbon application 
were met with Adobe's standard reply - the next major 
revision to their Mac OS products will be native for Mac OS 
X. This is a little perplexing because Acrobat 5 seems to be 
a Carbon application, but is registering as a Classic 
application. Actually, Adobe's delay in this area is 
attributable to the delays from Apple in getting the final 
version of IO Kit to developers. Adobe in particular has a 
hard need to be able to talk to external input devices, such 
as scanners. Without the IO Kit, doing this in OS X is 
essentially impossible, so for now, Adobe is in a wait status. 

Adobe wasn't the only vendor with a large presence at 
Seybold however. Corel, determined to regain the confidence 
that they have frittered away of late, had one of the larger 
non-Adobe booths. Hyping not only Corel Draw 10, but 
applications like Bryce, they are making a strong statement 
that anyone counting them out is doing so prematurely 
Corel said that they should have OS X native versions of all 
products but Corel Draw' 10 in time for MaeWorld Expo in 
New York, and that Draw 10 should be out in the fall. 

Another Mac perennial, Deneba Systems, 
http://www.den eba.com/ was showing off the capabilities of 
Canvas 8, the next revision of that venerable tool. Although 
Canvas 8 will be released for Windows first, this is not a sign 
that they are abandoning the Mac market. They felt it was 
better to delay the Mac version, so that it would be available 
as a Carbon application, rather than releasing the Classic 
version, and releasing another version for OS X almost 


immediately. In addition to Carbon, there are quite a few new 
features in Canvas 8 that make it well worth considering for 
current Canvas users, or those considering a switch. The first 
new r feature that drew r my attention was the addition of 
scripting to all aspects of Canvas. Both the Windows and Mac 
OS versions will be scriptable in their native environments. In 
addition, Deneba is using Adobe’s idea of actions, to create 
internal macros. They call the Canvas version Sequences, but 
regardless of name, they allow you to quickly automate 
repetitive tasks across the entire feature set. Sequences are 
cross platform, and can be called by either Visual Basic for 
Applications (VBA) scripts* or AppleScripts, Deneba also is 
looking into allowing Sequences to connect to scripts, so that 
a Sequence could pass results or data back to a script, thereby 
increasing the workflow capabilities of Sequences. Other 
features include new slicing tools, for w'eb graphics, and a 
bitmap preview r option, whereby you can take a vector image, 
see what the bitmap version will look like, and edit it without 
actually rasterizing the file. Once you are done, then you can 
convert the file to a bitmap image. This allows you to get a 
much better bitmap output of your file, without having to 
convert, undo, edit, convert again, or do all your editing as a 
bitmap. Finally, Deneba is implementing an online, shared 
editing system, so that Canvas users can easily set up a peer- 
to-peer (P2P) system for dealing with any document format 
that Canvas can handle. Deneba also assured me that Canvas 
8 will contain more than a few improvements aimed at the 
technical illustration users, who have been somewhat left out 
of the last set of version improvements* 

The final vendor of note was Sprockets, 
http://www.sprockets.com/. Sprockets provides online project 
management capabilities for companies. Although they didn't 
have as flashy a press conference as last year’s Seybold,, they did 
have some good news* including a partnership with enterprise 
storage vendor EMC. Also they were almost done validating their 
Java and other components on Mac OS X. (Note to vendors: If 
you want to please the press, a B-52s conceit is the way to go ) 
This company continues to catch my eye, as in this day of 
distributed workflow and teams, the serv ice they provide, and the 
way they charge is an excellent way for project-based companies 
to track and charge for work, wiLhout the kind of in-house 
servers and staff this level of product requires. 

Conclusion 

This was a very quiet Seybold compared to other years, 
which 1 attribute more to the transitional aspect of publishing 
these days. While print is still a big focus, the electronic 
aspects of publishing, such as electronic books, and other 
methods is going to be a major new' arena, and the w'ays of 
dealing with both in a coherent way haven't settled down 
yet. It definitely looks like Adobe's PDF will be the format of 
choice for output either w'ay, but the big struggle is still how 
to get from idea to output. !□ 
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TECH REVIEW 


By Ben Baumer 


Learning AppleScript the TecSoft Way 


Longtime Apple trainer Jerry Neilsen 
learns me some AppleScript 

Tf it’s possible for a someone wearing jeans and a 
bright red T-shirt emblazoned with the Pizza Factory logo 
to feel like a big shot, it might have been me during the 
“Workflow Automation with AppleScript" seminar hosted 
by TecSoft in Santa Monica last month. Not only did Apple 
validate my parking, saving me a cool 18 beans, but wtfre 
talking valet. The instructor of the course, Jerry Neilsen, 
was a likable, walrus-sized, bearded man with a loud and 
deep voice. He seemed like someone who could spend 
his Saturday nights regaling Telemachus with Trojan War 
stories, Jerry has a natural knack lor leaching that has 
been cultivated by years in the public school system, and 
it was a pleasure to learn AppleScript from him. 

Ol r Introduction to AppleScript 

After we were all assembled in the classroom, we ran 
through the introductions. The first thing that struck me 
about the group was the diversity of experience that we 
had all had on the Mac. There were graphic designers, 
production editors, dc facto office techies, somebody who 
worked for NASA, and me...the smart-ass Net Admin, I 
was blown away by how different all of our jobs seemed 
to be, yet for the most part we were all using the same 
apps (FileMaker, Quark, Cumulus, BBEditX Many of us 
had never had any previous formal training, but had 
simply put ourselves into positions to help others through 
independent learning. If there was one thing that united 
us, that was it. Furthermore, we were all there to take the 
next step in mastering our Macs, to tackle that nebulous 
AppleScript thing that we had heard so much about but 
never fully explored. 

Interestingly, everyone in the room claimed to have 
already written at least one original AppleScript. This was 
a stretch for me, and I thought for a moment that I would 


be the group's resident neophyte. However, I was the only 
student who had any significant programming experience, 
and this turned out to be much more helpful in learning 
AppleScript. As we all quickly found out, AppleScript is a 
lot more like C++ or java than it is like FileMaker's 
scripting language or Microsoft Office's Visual Basic for 
Applications, Jerry hammered home the point that while 
application-specific macro and scripting languages can 
operate only within the bounds of their application, 
AppleScript is capable of bridging applications and 
transferring data across. However, with this powerful 
ability comes increased complexity of code. 

It's my bet that if you have had experience 
programming in high-level languages like C++ or Java, 
you will likely find AppleScript to be incredibly intuitive 
and easy. In keeping with the Macintosh credo of user- 
friendly interfaces, AppleScript reads like plain English. 
Even if you are completely unfamiliar with AppleScript 
syntax, you might he able to get away with just typing in 
what you want to happen! The following line was in one 
of our more advanced AppleScripts: 

set fileList to (every file whose file type is 
"GIFf”) 

where fileList is an untyped variable. Simple, right? 
Weakly typed variables help to make AppleScript more 
accessible and less cumbersome for inexperienced 
programmers. Jerry likes to argue that AppleScript is noL 
just a scripting language, but a legitimate programming 
language. I don’t know if I agree with him on that, but his 
point that AppleScript is much more powerful and 
complex than a macro language, while still less powerful 
and complex than a full-scale programming language, is 
well taken. 

The Seminar Day-to-Day 

We spent most of the first day and a half in a lecture- 
type classroom, going through the TecSoft Persuasion 


Ben Baumer { netadmin@xplain.com) is the Network Administrator for the Xplain Corporation, He is hoping that this article will create such a firestorm 
that he will he able to launch a writing career and dominate the Best American Short Stories series for years to come 
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slide show. While I enjoyed Jerry's enthusiasm and found 
the presentation thorough, this part moved a little too 
slowly for me. If you have already learned programming, 
the concepts of if statements, repeat loops, and 
subroutines are simply old hat. All l really needed was a 
quick peek at the syntax and an answer to one or two 
questions like, “How do you declare local variables?" or 
“Does AppleScript include a case statement?" 

Day two was a nice blend of lecturing and hands-on 
scripting, Vm a big believer in learning to program with a 
keyboard and monitor in front of you, so I thirsted for the 
chance to actually write something in AppleScript, jerry 
helped us to customize Apple's ScriptEditor to 
automatically color-code our code, which seemed a little 
silly to me at the time, but has since proven invaluable. 
Before 1 knew it we were writing scripts that culled 
information from FileMaker databases or simple text files 
and placed it neatly in Quark documents. As soon as it 
became apparent how efficiently and easily AppleScript 
can move data between applications and documents, my 
thoughts turned immediately to my own job and where I 
would be able to use AppleScript to save time and stave 
off carpal tunnel syndrome. 1 could almost fee! the 
MacTeeh CD-ROM creation process getting simpler and 
more automated! 

The third and final day was by far the test. After a short 
morning lecture we broke into groups and settled into a 
longer project that we will explore in detail below. This is 
where Jerry's experience as a teacher really came through for 
me. Like a scruffy puppeteer he had orchestrated a situation 
that would result in maximal absorption of the material, I 
usually find planning programs out on paper to be too 
tedious and inconsequential for my MTV-addled brain, but in 
this case it did really help. I am a terrible group worker with 
an essentially binary attitude- either I'm calling the shots or 
Vm off in the corner staring at the girls in the cafeteria and 
dreaming about dunking on my Dad, But this was a 
productive group experience dial was beneficial to us all; we 
all understood the project much better when it was over 

Our Master AppleScript 

The best way to explain what we learned in the 
seminar might be to step through the code of our master 
group project and look at what's happening, The goal of 
ibis AppleScript is very general, and quite applicable to 
problems that most beginning scripters will want to use 
AppleScript to solve. The idea for this script is to drop 
text from a FileMaker database and images from a 
Cumulus database into a Quark template. Our code can 
be broken into three main tell blocks, each of which deals 
with a single application. This method of isolating 
applications in tell blocks is certainly not the only way 
write this AppleScript, but as it turns out, it is the fastest 


way* I think that it is also more instructive, since you only 
need to worry about one application at a time. 

In this first tell block, we move down FileMaker’s 
object hierarchy to isolate the data we want. In this 
example, we are only interested in records that are part of 
the “Z3” series. Accordingly, we use the show statement 
to show only those records, and then use another tell 
block to lock ourselves into that subset of data. This step 
eliminates the possibility of accessing data that is not in 
the M Z3” series, 

tell application "FileMaker Fra 5.0" 
tell document “BMW Text Database" 

shov (every record whose cell "Series" is "Z3") 
tell document 1 

set imageName to field "Image Name" 

- returns a list 

set textDesc to field "Text Description" 

- returns a list 
end tell 

end tell 
end tell 

Now, we can exploit a trick in FileMaker's AppleScript 
dictionary to store the data from all records in the found 
set into two variables (imageName and textDesc), The 
variables will be of data type list." Using the keyword 
“field 11 instead of “cell 11 returns a list of the data in all 
records, rather than just the data in one record. This 
enables us to grab all the information we need from 
FileMaker without using a time-consuming loop. I thought 
that this was a neat and compact way to store the data we 
wanted from FileMaker. The items in these two lists 
correspond with one another (i,e. - the first item in 
imageName comes from the same FileMaker record as the 
first item in textDesc). 

The next step in our script was to pull the paths to 
images stored in a Cumulus database. Cumulus, from 
Canto Software, is a top-flight media asset management 
tool for both Mac OS and Windows. The Cumulus 
“collection" in question acts as a central storage place for 
the multimedia files needed to complete this project. 
Again, we used a tell block to cordon off our Cumulus 
work, and a list to store the paths to the images. 

tell application "Cumulus S5*0” 

tell collection "BMW Image Database" 
set imagePath to I] 

— defines imagePath as an empty list 

set listlength to 0 

repeat with x in imageName 

set listlength to listlength + 1 

set next Image to (asset of every record whose 
name - x as string) 

set imagePath to imagePath & nextlmage 

- adds nextlmage to the list imagePath 
end repeat 

end tell 
end tell 

In this repeat loop, we step through the list of image 
names that we got from FileMaker (counting the number 
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of items at the same time) and match them with 
corresponding records in the Cumulus collection. The 
“asset 77 of each matched record is the full path to the 
image, which we will need when we want to import these 
image files into Quark. 

At this point we have all the information we need 
stored in three lists of equal length: imageName, 
imagePath, and textDesc. We also have the number of 
total records stored in the variable listlength. All we have 
to do is step through each list and drop the corresponding 
items into their appropriate places in our pre-formatted 
Quark template. Again, we used a tell block to talk 
exclusively to Quark. 

tell application "QuarkXPress™" 
activate 

set counter to 0 

- creates a variable that will help us keep track 
of which list Item we are accessing 
repeat listlength times 

set counter to counter + 1 
import file (item counter of imagePath) to 
picture box counter of spread 1 of document 1 

set bounds of image 1 of picture box counter of 
spread 1 of document 1 to proportional fit 

make new text at beginning of story 1 of text 
box counter of spread 1 of document 1 ”■ 

with properties Scontents:item counter of 
textDesc, size:12) 
end repeat 
end tell 

The counter variable helps us match up the 
corresponding list items and identify where we are in the 
list. The import file statement drops the appropriate 
image into the appropriate picture box using the path of 
the image file (from Cumulus). We then resize the image 
proportionally to fit the box. Next, we drop the 
corresponding text description (from FileMaker) of the 
image into the appropriate text box, and set the style of 
the text. This process repeats for each item in the list, and 
weTe done. 

What 1 liked about this assignment was the general 
applicability of the tasks that were performed. If you ever 
use FileMaker, Cumulus, or Quark, chances are high that 
you are going to be repetitively importing and exporting 
data from them. Since all of these applications are 
exceptionally scriptable, it is a good bet that you can use 
AppleScript to do some of this work for you, I felt like 
this was a perfect example of how to make AppleScript 
work for you, and I had never even heard of Cumulus 
before this seminar. 

Conclusion 

This seminar is by no means limited to those who 
work in the technology sector. In fact, the common 
characteristic that my classmates and 1 shared was not our 
profession or level of technical expertise, but the 
applications we used on a daily basis and a proclivity 


towards learning new r things on the Macintosh. If you are 
using scriptable applications like those mentioned in this 
article (be sure to include the Finder as well!) to do even 
mildly repetitive tasks, then you are a prime candidate to 
benefit from learning AppleScript. Both you and your 
company will see rewards, both immediate and in the 
long run. TecSofFs seminars can set you off and running 
in this direction. 

Part of me wants to argue that TecSoft should offer 
separate classes for those with programming experience 
and those without, but I can see that that reflects only my 
own experience with the seminar and ignores that of the 
majority. Despite my occasional boredom, die seminar 
was extremely effective in accomplishing its main goal: 
teaching us how to use AppleScript to make our jobs 
easier. If you've already learned a high-level 
programming language, you can probably get away with 
reading a book and practicing on your own, but I feel 
incredibly fortunate to have had access to a teacher like 
Jerry Neilsen. I appreciated getting the broad overview of 
AppleScript without having to read a book, and having a 
knowledgeable instructor Lhere to answer questions saved 
me some inevitable frustration Jerry impressed upon us 
vigilantly the importance of learning how to use an 
application’s dictionary on our own to find out how the 
program can be controlled by AppleScript, Since 
AppleScript is inherently dependent on third-party 
applications, this skill is not extra-credit, but par for the 
course, 1 definitely felt that by the end of the class, there 
w ere three things that Jerry had imparted to us that would 
allow me to learn all I ever wanted to know about 
AppleScript through practice and investigation: 

A fundamental understanding of applications' object 
hierarchies 

IIow to open, read, and understand an application's 
AppleScript dictionary 

How to use the AppleScript Help menu to flesh out 
syntactical problems. 

Simply put, the TecSoft course met its objectives. 
After having completed the course, 1 was able to write 
AppleScripts that enabled me to do my job more 
efficiently through the use of “Workflow Automation.” J 
have Jerry Neilsen and TecSoft to thank for that, and as 
such, I give the seminar high marks. 

References 
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Jabber 


Last month we tegan our coverage of P2P (peer-to-peer) 
technologies. The P2P field is l>eing fueled by open-source projects 
which have sprung up in response to the popularity of specific 
proprietary applications in this genre, by generalizing, improving, or 
simply imitating them. last month we discussed Gnutella, an open- 
source protocol for peer-to-peer sharing of files and other resources. 
Gnutella was inspired by Napster, generalizing the concept to 
support sharing of things other than music files, and decentralizing 
searches to avoid any one critical point which could be attacked, by 
eititer technological or legal means. This month we are going to look 
into jabber, which takes its cue from instant messaging (IM) and chat 
products such as AIM (AOL Instant Messenger), Yahtx) Pager, MSN 
Messenger, ICQ, and IRC. Jabber’s goal is to provide a “universal" 
XML-based platform for instant messaging, which can bridge to 
other protocols as well as support new applications of messaging. 

Jabber originated with Jeremie Miller's frustration with 
having to use multiple pieces of IM software in order to keep up 
with all of his friends, who were using a variety of different IM 
systems. His response to this proliferation was to come up with 
a protocol which was designed to both serve as a messaging 
platform on its own and to transparently bridge to others, so that 
he could use one protocol (and one client application) to 
communicate with all of his friends. Unsurprisingly, he chose 
XML as the basis for Jabber. So what is Jabber, exactly? 

Jabber in a Nutshell 

jabber isn’t a specific application, and the Jabber community 
likes to point out that it isn't a protocol either—they prefer to call ii 
a platform. In truth, Jabber represents a collection of XML-based 
message formats, and the protocol for communicating them* 

Jabber is completely XML-based, and communicates over 
client-server based TCP/IP connections, modeled on the email 
system. Users are identified by Jabber IDs, which resemble email 
addresses, and are of the form user@server/resource. (The 
“resource” portion allows the same user to connect multiple times 
from different applications or locations, and so the name of the client 
application or location, such as “home” or laptop 11 , is often used.) 
Jabber users begin a session by connecting to their local jabber 
server. Messages are sent by addressing them to other jabber IDs 
and handing them off to the local server, which routes them to the 
remote user's server in a manner similar to how email is routed and 


delivered The remote user then receives the message via a 
connection to his local server. 

Jabber's design philosophy takes XML seriously, and also sees 
as fundamental the placing of the bulk of the logic on the server. 
As mentioned above, one of Jabber's original goals was to bridge 
to other IM system, so that Jabber users could talk to other IM 
users without either really having to care or fully realize that they 
are using different systems. The technology which allows this 
accordingly lives on the server side, and Jabber users bridge to 
other IM systems by having the server act as their proxy—from the 
point of view of the foreign IM system, the server is the AIM client 
(for example), and it takes care of translating Jabber messages into 
AIM messages, and vice versa. This translation is done by 
components of the server called ' transports" (or more recently, just 
"components”). The value of this approach is that it makes the 
creation of Jabber clients relatively simple, and additional 
functionality can be added by upgrading Jabber servers, without 
requiring a widespread client upgrade. 

But Jabber doesn't just bridge to other systems—in the ideal 
situation, everyone could just use Jabber natively. As an IM 
technology in its own right, Jabber is full-featured: it supports 
“buddy lists” as well as notification of whether these users are 
currently online. It goes a step further than most other LM systems, 
in that buddy lists (called “rosters”) are stored server-side, which 
facilitates notification of online status (called “presence”), as well as 
allowing users to connect to Jabber server from different machines 
using different client software without having to keep separate 
rasters in sync. Additionally, notification under Jabber occurs only 
with consent—a user must “subscribe" to another user in order to 
receive notification of whether they are online, and the other user 
has to authorize the subscription. This affords additional privacy, 
and could be used to combat spammers (by refusing messages 
from users to which one is not already subscribed, for instance). 
Also, jabber supports die concept of traditional IM messages 
(which Jabber calls "chat”), group chats similar to IRC (called 
“group char"), and more passive messages. 

Strengths and Weaknesses 

In additional to serving as a traditional human-to-human 
communication technology, Jabber is aspiring to serve as a 
mechanism for facilitating application-to-application (A2A) 
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communication, or as a middleware to transport other types of 
messages* Fanciful potential applications include “smart" appliances 
which communicate in order to negotiate for resources (such as a 
coffee pot which turns itself on when the alarm clock goes off)* As 
of yet, there don t seem to any applications in this arena, and it 
isn't dear if this is a reasonable goal—cither technologies such as 
Java’s jini have not seemed to take off in the "smart appliance” area, 
and tor more traditional application-to-application communication 
there is already a great deal of underutilized technology out there, 
and die idea of an Al-like communication between desktop 
applications isn't realistically on the horizon. As a transport 
mechanism for odier forms of inter-process communication there is 
potential, but Jabber doesn't have a clear advantage over die 
alternatives already available, and for .some applications a protocol 
more directly designed for diis task might work better. 

In general, Jabber seems to suffer a little from what I would call 
die “premature need for generalization' 1 , and this is just one of die 
symptoms* Although Jabber is try ing to lie general-purpose, it's dear 
that it was designed with instant messaging in mind—for instance, 
its message types are “chat", “gruupchaf, “default", and “error'. In 
truth, many of the new XML-based protocols tcxlay are trying to fill 
some perceived general need at the same time they are trying to fill 
a specific one, In general, Fd prefer to see a strong solution to a 
particular problem (such as the need for an open instant messaging 
protocol) t and have generalization come later, if it’s really needed 
and after some experience has lieen gained with die concrete 
application. Then, the original use could become one application of 
a more general technology, possibly after ^implementation. 

Jabber is composed of open protocols and formats, and there 
are open-source implementations of clients and servers as well* 
The importance of this shouldn’t be underestimated* in light of the 
proliferation of mutually incompatible, restrictive IM technologies. 
But the most valuable and immediately useful aspects of Jabber, 
in my opinion, aren’t really the direct consequence of the “open 
source* approach: they are actually security-related First* it's 
straightforward for companies to set up a private Jabber server 
behind the corporate firewall. 'This is actually more significant 
than it may sound, because despite the inherent insecurity of 
using AIM (for instance) for communication of confidential 
material, it's so useful that people often do it anyway. With Jabber* 
all of this communication can happen without the need for it to 
pass through an external server, whose security isn't under the 
control of its users. In the same vein. Jabber is incorporating 
support for encryption, both PGP-like procedures for die 
encryption of message content, and SSL for encryption of client- 
server and server-server communication. They do get points off, 
however, for not incorporating this from the start; we have 
enough insecure protocols which originated while the internet 
was a safe, private playground, and anyone developing new 
protocols today has no excuse for ignoring the need for some 
level of encryption as a fundamental component. 

Jabber Resources 

If you’re interested in Jabber from a developer’s perspective (or 
as a user, for that matter), die central hub of all tilings Jabber is 


Jabberorg Here you can find developer documentation, as well as 
FAQs t user guides, and links to client implementations. Developers 
will want to look at the Technology Overview, the Protocol 
Overview, and the Programmers Guide, as well as the links to 
available code libraries. Also* those implementing Jabber clients in 
particular will want to check out The Jabber Client Developer’s Cheat 
Sheet, which will help steer you around the “gotchasd For examples 
of some alternative uses of Jabber, take a look at DJ Adams’ articles 
on the O’Reilly Network, or on Ids own Fun with Jabber site, Adams' 
applications use the Net:;Jabber Perl module, which makes this sort 
of experimentation a snap, and you'll want to get your hands on this 
if you are Peri-savvy. He also has an experimental implementation 
of doing XML-RPC over Jabber* O'Reilly lias some additional general 
coverage of Jabber, Ixith on their portal site and in their Peer-to-Peer \ 
Fxxik, the Jabber chapter of which is available online* Finally, try Eric 
Peyton’s Fire IM client for Mac OS X, which supports Jabber as well 
as a variety of other IM protocols, and keep an eye onJabberCentral 
for coverage of current related news. 
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Fun With Jabber 

<http://www.pipetree.com/jabber/> 

Net::Jabber 

<http://search.cpan.org/search?dist=Net-Jabber> 

XMLRPC over Jabber 

<http://www.pipetree.com/jabber/XMLRPC/> 

XML Messaging with Jabber [Oct. 06,2000] 
<hnp://www.openp2p.com/pub/a/p2p/2000/10/06/jabbeLxmI.html> 

Jabber Works: Here's How [Oct. 06,2000] 
<http://www.openp2p.eom/pub/a/p2p/2000/10/06/jabber_workshtml> 
Peer-to-Peer: Chapter 6: Jabber 
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drop" functionality. 

Our expert team offers you 60 days of individual installation support 
via phone, fax or email. 


SuSE Inc. 

580 Second Street 
Oakland, CA 94607 

irf0@su5e.com 
Phone; (888) UR-LINUX 
(510) 628-3380 
Faxt (510)628-3381 



Place your order today! www.suse.com 
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M ac developers depended on CodeWarrior to make the 
platform architecture shift from 68K to PowerPC 
processors. Now CodeWarrior does it again, speeding your 
transition to the next new operating system. CodeWarrior for 
Mac OS, Version 6.0 supports development for both OS X 


and Classic Mac operating systems from a single, powerful, 
award-winning Integrated Development Environment. 
Discover how CodeWarrior for Mac OS, Version 6.0 can 
help you realize your Mac development dreams. 

Visit www.metrowerks.com/go/mac. 


Keeping Mac 


dreams alive 
since 1993. 
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